Getting Started

This guide is the recommended way to integrate Hive content.

1. Install

npm install hive-cms

pnpm add hive-cms

yarn add hive-cms

bun add hive-cms

2. Configure

Create an environment variable on your server runtime:

HIVE_API_KEY=your_public_api_key

The SDK is server-first. If loaded in a browser runtime, it logs a warning.

By default, the SDK reads HIVE_API_KEY automatically from your server environment.

3. Create a client

import { Hive } from 'hive-cms';

const hive = new Hive();

If your variable uses a different name:

const hive = new Hive({
  apiKeyEnvVarName: 'MY_HIVE_KEY',
});

You can still pass apiKey directly when needed.

4. Next.js integration

Use the SDK inside Route Handlers or Server Components.

// app/api/posts/route.ts
import { NextResponse } from 'next/server';
import { Hive } from 'hive-cms';

const hive = new Hive();

export async function GET() {
  try {
    const posts = await hive.posts.list({ limit: 10 });
    return NextResponse.json(posts);
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    return NextResponse.json({ message }, { status: 500 });
  }
}

// app/blog/page.tsx
import { Hive } from 'hive-cms';

const hive = new Hive();

export default async function BlogPage() {
  const posts = await hive.posts.list({ limit: 10 });

  return (
    <main>
      <h1>Blog</h1>
      <ul>
        {posts.data.map((post) => (
          <li key={post.slug}>{post.title}</li>
        ))}
      </ul>
    </main>
  );
}

5. Express.js integration

import express from 'express';
import { Hive } from 'hive-cms';

const app = express();
const hive = new Hive();

app.get('/content/posts', async (_req, res) => {
  try {
    const posts = await hive.posts.list({ limit: 10 });
    res.json(posts);
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ message });
  }
});

6. Common calls

await hive.posts.list({ limit: 10 });
await hive.posts.get('welcome-to-hive');
await hive.tags.list();
await hive.categories.list();
await hive.authors.list();
await hive.stats.get();

Error handling

The SDK throws HiveApiError with structured context.

import { HiveApiError } from 'hive-cms';

try {
  await hive.posts.list();
} catch (error) {
  if (error instanceof HiveApiError) {
    console.error(error.message); // pretty, multi-line message
    console.error(error.status, error.code, error.details);
  }
}

Technical notes

• Default base URL: https://api.hivecms.online/api/public
• Default version: v1
• You can override with custom strings:

const custom = new Hive({
  baseUrl: 'https://your-domain.com/api/public',
  version: 'v1',
});

const customEnvName = new Hive({
  apiKeyEnvVarName: 'MY_HIVE_KEY',
});

API fallback (secondary)

If you need raw HTTP details, use API Reference.

Direct endpoint style:

GET /api/public/v1/{API_KEY}/posts

SDK should remain your primary integration path.

The Hive Public Content API is versioned. v1 is the current stable version. The version should be included in the URL path immediately after /api/public.

Supported URL formats:

• Recommended: https://api.hivecms.online/api/public/v1/{API_KEY}/posts
• Legacy (auto-routes to v1): https://api.hivecms.online/api/public/{API_KEY}/posts

We recommend using the explicit /v1/ format for clarity, as future API versions will be maintained separately.

Authentication

The Hive Public Content API uses API key authentication. Your API key is included directly in the URL path.

Getting Your API Key

You can obtain your API key from your Hive workspace. The key is read-only and maps directly to your workspace, so keep it private.

Using Your API Key

Replace {API_KEY} in each endpoint URL with your actual API key. For example:

# Before
https://api.hivecms.online/api/public/v1/{API_KEY}/posts

# After (with your actual key)
https://api.hivecms.online/api/public/v1/your-actual-key-here/posts

Making Requests

The public API is configured for simple GET requests. No special headers are required, so you can call it directly from:

• Browser: Use fetch() or XMLHttpRequest
• cURL: Use the command line examples provided in each endpoint
• Any HTTP client: Standard GET requests work out of the box

Example Request

Here's a simple example using cURL:

curl "https://api.hivecms.online/api/public/{API_KEY}/posts?limit=5"

Or using JavaScript in the browser:

const response = await fetch(
  'https://api.hivecms.online/api/public/{API_KEY}/posts?limit=5'
);
const data = await response.json();
console.log(data);

Response Format

All successful responses return JSON data. Error responses also use JSON with a message field describing the issue.

Success Response

{
  "data": [...],
  "total": 42,
  "offset": 0,
  "limit": 10
}

Error Response

{
  "message": "Invalid API key"
}

Next Steps

• Learn about Response Shapes to understand the data structure
• Explore the Posts API to fetch content
• Check out other endpoints like Tags and Categories