BlogCore API Reference

BlogCore is a centralized blog API backend you deploy once and connect to any number of client projects. Instead of rebuilding a blog system from scratch for every product, you integrate via API key. One backend, unlimited frontends — a marketing site, a SaaS dashboard, a mobile app, and a partner's storefront can all publish through the same BlogCore instance while staying completely isolated from one another.

Who this page is for. If you're evaluating BlogCore for a project, the Introduction and Core Concepts sections below explain the model in plain terms. If you're implementing the integration, jump to Quick Start, then the endpoint reference for the resource you need.

Five ideas to understand before touching an endpoint.

1. Platforms (tenants)

A Platform represents one connected project — your client's marketing site, your SaaS blog, your personal site. Every piece of data (posts, users, media, analytics) belongs to exactly one platform. Platforms cannot see or affect each other's data.

2. API keys

Each platform has one or more API keys. A key has two parts:

3. Platform users

BlogCore does not replace your authentication system. For user-scoped operations, you pass your own user's identity via request headers. BlogCore creates a lightweight PlatformUser record the first time it sees a new identity, and tracks that user's posts, role, and activity from then on.

4. Roles & permissions

Every platform user has a role: owner, editor, author, or viewer. Roles determine what API actions that user can perform — publishing, approving posts, deleting media, managing webhooks, and so on. See the full Permissions Reference.

5. Post status state machine

[draft] ▸ [pending_review] ▸ [in_review] ▸ [approved] ▸ [published]
     │                                                                  │
     │  (workflow_enabled = false: skip straight to approved/published)  │
     └──────────────────────────────────────────────▸──▸
                                              [rejected] ◂─── (from review)
                                              [archived] ◂─── (from any state)

A post can also be scheduled: set scheduled_at to a future timestamp while the post is draft or approved. A background job checks every five minutes and publishes it automatically once that time arrives — you don't need to poll or trigger anything yourself.

Get your first list of posts in under five minutes.

BLOGCORE_URL=https://blogcore.jamiuadewaleyusuf.com
BLOGCORE_API_KEY=pk_live_xxxxxxxxxxxx
BLOGCORE_API_SECRET=sk_xxxxxxxxxxxx

curl "https://blogcore.jamiuadewaleyusuf.com/api/v1/posts?status=published" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_xxxxxxxxxxxx"

const res = await fetch(`${process.env.BLOGCORE_URL}/api/v1/posts?status=published`, {
  headers: {
    'X-API-Key':    process.env.BLOGCORE_API_KEY,
    'X-API-Secret': process.env.BLOGCORE_API_SECRET,
  }
});
const { data, meta } = await res.json();
// data = array of posts, meta = { current_page, per_page, total }

$response = Http::withHeaders([
    'X-API-Key'    => 'pk_live_xxxx',
    'X-API-Secret' => 'sk_xxxx',
])->get('https://blogcore.jamiuadewaleyusuf.com/api/v1/posts', [
    'status' => 'published',
])->json();

import requests

r = requests.get(
    "https://blogcore.jamiuadewaleyusuf.com/api/v1/posts",
    params={"status": "published"},
    headers={"X-API-Key": "pk_live_xxxx", "X-API-Secret": "sk_xxxx"},
)
posts = r.json()["data"]

{
  "success": true,
  "data": [{
    "id":             "01JXXXXXXXXXXXXXXX",
    "title":          "My First Blog Post",
    "slug":           "my-first-blog-post",
    "excerpt":        "A short summary...",
    "content":        "<p>Full HTML content...</p>",
    "content_format": "html",
    "status":         "published",
    "reading_time":   4,
    "published_at":   "2026-01-15T10:30:00Z",
    "author":         { "id": "...", "name": "Adewale", "email": "..." },
    "featured_image": { "url": "https://res.cloudinary.com/...", "alt_text": "..." },
    "categories":     [{ "id": "...", "name": "Laravel", "slug": "laravel" }],
    "tags":           [{ "name": "php", "slug": "php" }],
    "seo": { "title": "...", "description": "...", "keywords": [] }
  }],
  "meta": { "current_page": 1, "per_page": 15, "total": 42, "last_page": 3 }
}

Every platform API request requires two headers that identify and authorize your platform.

Key permission scoping

You can create multiple keys per platform, each with a different permission scope. For example, a restricted read-only key that's safe to use in a public-facing frontend proxy:

curl -X POST https://blogcore.jamiuadewaleyusuf.com/api/v1/admin/platforms/{id}/keys \
  -H "X-Super-Admin-Secret: <your admin secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Public Frontend (read-only)",
    "permissions": ["posts.read", "analytics.read"]
  }'

const { data, secret } = await fetch(`${BASE}/api/v1/admin/platforms/${platformId}/keys`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Super-Admin-Secret': process.env.BLOGCORE_SUPER_ADMIN_SECRET,
  },
  body: JSON.stringify({
    name: "Public Frontend (read-only)",
    permissions: ["posts.read"],
  }),
}).then(r => r.json());
// SAVE secret NOW — it is only shown once

BlogCore does not replace your authentication system. For user-scoped operations (creating posts, AI generation, approvals), pass your user's identity via request headers. BlogCore will auto-create a platform user record the first time it encounters a new identity.

Example: Next.js with NextAuth

// app/api/blog/posts/route.ts
import { getServerSession } from "next-auth"

export async function POST(req: Request) {
  const session = await getServerSession();
  const body    = await req.json();

  const res = await fetch(`${process.env.BLOGCORE_URL}/api/v1/posts`, {
    method: 'POST',
    headers: {
      'Content-Type':  'application/json',
      'X-API-Key':     process.env.BLOGCORE_API_KEY!,
      'X-API-Secret':  process.env.BLOGCORE_API_SECRET!,
      'X-User-Id':     session.user.id,      // your user's ID
      'X-User-Email':  session.user.email,
      'X-User-Name':   session.user.name,
    },
    body: JSON.stringify(body),
  });
  return Response.json(await res.json());
}

Checking what the current identity can do

Before rendering write actions in your own UI (a Publish button, an Approve/Reject panel), ask BlogCore what the acting identity is actually allowed to do rather than assuming. This is the same check BlogCore itself enforces server-side, so your UI and your permissions never drift out of sync.

{
  "success": true,
  "data": {
    "platform": { "id": "01JXXXXX", "name": "Acme Corp Blog", "workflow_enabled": true },
    "user": { "id": "01JXXXXX", "name": "Adewale", "email": "adewale@example.com", "role": "editor" },
    "permissions": ["posts.create", "posts.read", "posts.update", "posts.publish", "media.upload", "analytics.read"]
  }
}

The core resource. All post endpoints require the standard X-API-Key / X-API-Secret headers; write actions also require X-User-Id or X-User-Email.

curl https://blogcore.jamiuadewaleyusuf.com/api/v1/posts/slug/my-first-blog-post \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_xxxx"

Which endpoint to use?

Every platform has workflow_enabled set to true or false. This decides which of the two publishing paths below applies to it.

Every update to a post's title or content is automatically snapshotted before the change is applied — there is no separate "enable versioning" step.

Categories support one level of nesting via parent_id. A post can belong to multiple categories.

Tags are flat (no nesting) and are usually created implicitly — passing a new tag name when creating or updating a post is enough; you rarely need to call these endpoints directly.

Uploads are stored on Cloudinary under a per-platform folder. BlogCore returns the secure URL plus three auto-generated size variants (thumbnail, medium, large) so you rarely need to do your own image resizing.

curl -X POST https://blogcore.jamiuadewaleyusuf.com/api/v1/media \
  -H "X-API-Key: pk_live_xxxx" -H "X-API-Secret: sk_xxxx" \
  -H "X-User-Id: user_123" \
  -F "file=@cover.jpg" \
  -F "alt_text=A sunset over the harbor"

{
  "success": true,
  "data": {
    "id": "01JXXXXX",
    "secure_url": "https://res.cloudinary.com/.../cover.jpg",
    "resource_type": "image",
    "width": 1600, "height": 900,
    "variants": {
      "thumbnail": { "url": "...", "width": 150, "height": 150 },
      "medium":    { "url": "...", "width": 600, "height": 400 },
      "large":     { "url": "...", "width": 1200, "height": 800 }
    }
  }
}

Lightweight, first-party view tracking — no third-party script on your pages, no cookies required. Send an event when a reader views a post; BlogCore aggregates it into daily summaries automatically.

Every AI endpoint requires ai.use and, since generated content is attributed to a real author, a user identity header. Each platform has a monthly token quota (default 500,000, configurable per-platform) — once it's reached, requests return 429 AI_LIMIT_EXCEEDED until the quota resets on the 1st of the month.

AI endpoints at a glance

Register a URL to receive a POST request whenever something happens on your platform — a post is published, a file is uploaded, and so on — instead of polling the API.

Verifying the signature

Every webhook delivery includes an X-BlogCore-Signature header in the format sha256=<hex> — an HMAC-SHA256 of the raw JSON body, signed with the webhook's own secret. Always verify this before processing, to reject spoofed requests.

// app/api/blogcore-events/route.ts
import crypto from 'crypto'

export async function POST(req: Request) {
  const rawBody   = await req.text();
  const signature = req.headers.get('x-blogcore-signature') ?? '';
  const expected  = 'sha256=' + crypto
    .createHmac('sha256', process.env.BLOGCORE_WEBHOOK_SECRET!)
    .update(rawBody)
    .digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  const valid = crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!valid) return Response.json({ error: 'Bad signature' }, { status: 401 });

  const payload = JSON.parse(rawBody);

  switch (payload.event) {
    case 'post.published':
      await revalidateBlogPath(`/blog/${payload.data.slug}`);
      break;
    case 'post.rejected':
      await notifyAuthorByEmail(payload.data.author.email, 'Your post was rejected');
      break;
  }

  return Response.json({ ok: true }); // must return 2xx within 10s
}

// routes/api.php
Route::post('/blogcore-events', function(Request $request) {
    $signature = $request->header('X-BlogCore-Signature', '');
    $expected  = 'sha256=' . hash_hmac('sha256', $request->getContent(), config('services.blogcore.webhook_secret'));

    if (!hash_equals($expected, $signature)) {
        return response()->json(['error' => 'Bad signature'], 401);
    }

    $payload = $request->json()->all();

    match ($payload['event']) {
        'post.published' => dispatch(new ClearBlogCache($payload['data']['slug'])),
        'post.rejected'  => dispatch(new NotifyAuthorOfRejection($payload['data'])),
        default          => null,
    };

    return response()->json(['ok' => true]);
})->withoutMiddleware([\App\Http\Middleware\VerifyCsrfToken::class]);

import hmac, hashlib
from flask import Flask, request, abort, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = b"your_webhook_secret_here"

@app.route("/blogcore-events", methods=["POST"])
def handle_webhook():
    sig      = request.headers.get("X-BlogCore-Signature", "")
    expected = "sha256=" + hmac.new(WEBHOOK_SECRET, request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(sig, expected):
        abort(401, "Bad signature")

    payload = request.get_json()
    event   = payload["event"]

    if event == "post.published":
        clear_cache(payload["data"]["slug"])
    elif event == "post.rejected":
        send_rejection_email(payload["data"])

    return jsonify({"ok": True})

const express = require('express');
const crypto  = require('crypto');
const app     = express();

// Must use the raw body for HMAC — parse before any JSON middleware
app.post('/blogcore-events', express.raw({ type: 'application/json' }), (req, res) => {
  const sig      = req.headers['x-blogcore-signature'] ?? '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.BLOGCORE_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Bad signature' });
  }

  const payload = JSON.parse(req.body.toString());
  // handle payload.event ...
  res.json({ ok: true });
});

Webhook payload structure

{
  "event":       "post.published",
  "platform_id": "01JXXXXXXXXXXXXXXX",
  "timestamp":   "2026-01-15T10:30:00Z",
  "data": {
    "id":           "01JXXXXXXXXXXXXXXX",
    "title":        "Getting Started with Laravel Queues",
    "slug":         "getting-started-with-laravel-queues",
    "status":       "published",
    "published_at": "2026-01-15T10:30:00Z",
    "author":       { "id": "...", "name": "Adewale", "email": "..." }
  }
}

All events reference

App Router, Server Components and Server Actions. Because the API secret must never reach the browser, every call goes through server-side code — never a client component.

1. A typed client wrapper

// lib/blogcore/client.ts — server-only
import "server-only";

export class BlogcoreError extends Error {
  constructor(message: string, public readonly status: number, public readonly code?: string) {
    super(message);
  }
}

export async function blogcoreFetch<T>(path: string, options: RequestInit & { actingUser?: { id: string; email: string; name: string } } = {}): Promise<T> {
  const { actingUser, headers, ...rest } = options;
  const res = await fetch(`${process.env.BLOGCORE_URL}/api/v1${path}`, {
    ...rest,
    headers: {
      Accept: "application/json",
      "X-API-Key": process.env.BLOGCORE_API_KEY!,
      "X-API-Secret": process.env.BLOGCORE_API_SECRET!,
      ...(actingUser ? {
        "X-User-Id": actingUser.id, "X-User-Email": actingUser.email, "X-User-Name": actingUser.name,
      } : {}),
      ...headers,
    },
  });

  const body = await res.json().catch(() => null);
  if (!res.ok) throw new BlogcoreError(body?.error?.message ?? "Request failed", res.status, body?.error?.code);

  // The posts list endpoint returns {data, links, meta} directly; everything
  // else is wrapped as {success, data} — normalize both to just the payload.
  return (body && typeof body === "object" && "success" in body) ? body.data : body;
}

2. Reading posts in a Server Component

// app/blog/page.tsx
import { blogcoreFetch } from "@/lib/blogcore/client";

export default async function BlogPage() {
  const { data: posts } = await blogcoreFetch<{ data: any[] }>(
    "/posts?status=published&sort_field=published_at&sort_dir=desc",
    { next: { revalidate: 60, tags: ["posts"] } } // ISR — revalidate every 60s
  );

  return (
    <main>
      {posts.map((post) => (
        <a key={post.id} href={`/blog/${post.slug}`}>{post.title}</a>
      ))}
    </main>
  );
}

3. Publishing a post from a Server Action

// app/admin/actions.ts
"use server";
import { revalidateTag } from "next/cache";
import { blogcoreFetch } from "@/lib/blogcore/client";

export async function publishPostAction(formData: FormData) {
  const id = String(formData.get("id"));
  await blogcoreFetch(`/posts/${id}/publish`, {
    method: "POST",
    actingUser: { id: "admin", email: "you@example.com", name: "Admin" },
  });
  revalidateTag("posts"); // invalidates every cached fetch tagged "posts"
}

In Nuxt, keep the API secret in a server route or a Nitro server util — never in a plain composable that runs in the browser.

// server/utils/blogcore.ts — runs only on the Nitro server
export async function blogcoreFetch<T>(path: string, opts: RequestInit = {}): Promise<T> {
  const config = useRuntimeConfig();
  const res = await $fetch<any>(`${config.blogcoreUrl}/api/v1${path}`, {
    ...opts,
    headers: {
      "X-API-Key": config.blogcoreApiKey,
      "X-API-Secret": config.blogcoreApiSecret,
      ...opts.headers,
    },
  });
  return ("success" in res) ? res.data : res;
}

// server/api/posts.get.ts
export default defineEventHandler(async () => {
  return blogcoreFetch("/posts?status=published");
});

// composables/usePosts.ts — calls YOUR OWN /api/posts route, never BlogCore directly
export function usePosts() {
  return useFetch("/api/posts");
}

Usage in a page

Add blogcoreUrl, blogcoreApiKey, and blogcoreApiSecret to the runtimeConfig block in nuxt.config.ts, sourced from environment variables.

Uses Laravel's built-in HTTP client — no extra package required.

// app/Services/BlogcoreClient.php
namespace App\Services;

use Illuminate\Support\Facades\Http;

class BlogcoreClient
{
    public function __construct(
        private readonly string $baseUrl = null,
    ) {
        $this->baseUrl = config('services.blogcore.url');
    }

    private function client(?array $user = null)
    {
        return Http::withHeaders(array_filter([
            'X-API-Key'    => config('services.blogcore.key'),
            'X-API-Secret' => config('services.blogcore.secret'),
            'X-User-Id'    => $user['id'] ?? null,
            'X-User-Email' => $user['email'] ?? null,
        ]))->baseUrl("{$this->baseUrl}/api/v1");
    }

    public function posts(array $query = []): array
    {
        return $this->client()->get('/posts', $query)->json();
    }

    public function createPost(array $data, array $user): array
    {
        return $this->client($user)->post('/posts', $data)->throw()->json('data');
    }
}

Register the config in config/services.php:

'blogcore' => [
    'url'    => env('BLOGCORE_URL'),
    'key'    => env('BLOGCORE_API_KEY'),
    'secret' => env('BLOGCORE_API_SECRET'),
],

Then inject it anywhere via Laravel's container:

public function index(BlogcoreClient $blogcore)
{
    return view('blog.index', [
        'posts' => $blogcore->posts(['status' => 'published'])['data'],
    ]);
}

Works with any framework — Flask, Django, FastAPI — since it's a plain requests-based client with no framework dependency.

# blogcore.py
import os
import requests

class BlogcoreError(Exception):
    def __init__(self, message, status, code=None):
        super().__init__(message)
        self.status = status
        self.code = code

class BlogcoreClient:
    def __init__(self):
        self.base_url = os.environ["BLOGCORE_URL"]
        self.headers = {
            "X-API-Key": os.environ["BLOGCORE_API_KEY"],
            "X-API-Secret": os.environ["BLOGCORE_API_SECRET"],
        }

    def _request(self, method, path, user=None, **kwargs):
        headers = {**self.headers}
        if user:
            headers.update({
                "X-User-Id": user.get("id", ""),
                "X-User-Email": user.get("email", ""),
                "X-User-Name": user.get("name", ""),
            })
        res = requests.request(method, f"{self.base_url}/api/v1{path}", headers=headers, **kwargs)
        body = res.json()
        if not body.get("success", True) and not res.ok:
            err = body.get("error", {})
            raise BlogcoreError(err.get("message", "Request failed"), res.status_code, err.get("code"))
        return body.get("data", body)

    def get_posts(self, **params):
        return self._request("GET", "/posts", params=params)

    def create_post(self, data, user):
        return self._request("POST", "/posts", user=user, json=data)

Usage

client = BlogcoreClient()
posts = client.get_posts(status="published")

post = client.create_post(
    {"title": "Hello, BlogCore", "content": "<p>First post</p>"},
    user={"id": "user_123", "email": "you@example.com", "name": "Adewale"},
)

Recommended pattern: server proxy

Mobile App  ──▶  Your backend (holds the secret)  ──▶  BlogCore

The mobile app authenticates to your backend using whatever
you already use (Firebase Auth, a JWT, session cookies). Your
backend then forwards the request to BlogCore, attaching the
API key/secret server-side, and returns BlogCore's response.

// mobile app — calls your own backend, never BlogCore directly
async function getPosts() {
  const res = await fetch("https://your-backend.com/api/blog/posts", {
    headers: { Authorization: `Bearer ${await getUserToken()}` },
  });
  return res.json();
}

// your backend (e.g. an Express route) — the only place with BlogCore credentials
app.get("/api/blog/posts", authenticateUser, async (req, res) => {
  const upstream = await fetch(`${process.env.BLOGCORE_URL}/api/v1/posts?status=published`, {
    headers: {
      "X-API-Key": process.env.BLOGCORE_API_KEY,
      "X-API-Secret": process.env.BLOGCORE_API_SECRET,
    },
  });
  res.json(await upstream.json());
});

This is the same shape used by the Next.js and Vue guides above — the browser (or app) only ever talks to a server you control, and that server is the only thing that ever sees the BlogCore secret.

Every error follows the same JSON shape, so your error handler never needs to special-case the structure:

{
  "success": false,
  "error": {
    "code":    "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "title": ["The title field is required."],
      "seo.description": ["The seo.description may not be greater than 160 characters."]
    }
  }
}

Error handling example

async function blogcoreRequest(path, options = {}) {
  const res  = await fetch(`${BASE}/api/v1${path}`, options);
  const json = await res.json();

  if (!json.success) {
    const { code, message, details } = json.error;
    switch (code) {
      case 'INVALID_API_KEY':
        throw new Error('BlogCore credentials invalid — check environment variables');
      case 'VALIDATION_ERROR': {
        const fieldErrors = Object.entries(details).map(([f, m]) => `${f}: ${m[0]}`).join('; ');
        throw new Error(`Validation failed — ${fieldErrors}`);
      }
      case 'AI_LIMIT_EXCEEDED':
        throw new Error('Monthly AI quota reached — try again next month');
      default:
        throw new Error(message ?? 'An unexpected error occurred');
    }
  }
  return json.data;
}

Permissions are checked at two levels: the API key (what the integration is allowed to do at all) and the acting user's role (what that specific person is allowed to do). Both must allow an action for it to succeed.

Can I use BlogCore without a workflow?

Yes. Leave workflow_enabled as false (the default). Anyone with posts.publish can publish directly with POST /posts/{id}/publish. The multi-stage review only activates once you enable it, and you can toggle it at any time without affecting existing posts.

Do I need to pre-register users before they can create posts?

No. BlogCore auto-registers users on first encounter (governed by BLOGCORE_AUTO_REGISTER_USERS, default on). Just pass X-User-Id or X-User-Email and BlogCore creates a platform user with the default author role. You can change their role afterward.

How do scheduled posts actually get published?

Set scheduled_at to a future timestamp on a draft or approved post. A scheduled job checks every five minutes for posts whose time has arrived and publishes them the same way POST /posts/{id}/publish would. You don't need to call anything yourself once it's scheduled — just make sure this server's task scheduler (php artisan schedule:run via cron) is actually running in your deployment.

Are media files served via BlogCore or directly from Cloudinary?

Directly from Cloudinary. BlogCore only stores the metadata and URLs — images are served from Cloudinary's CDN, so your readers never route through this server for assets.

What happens if the Groq API is down?

AI endpoints retry twice on a 5xx from Groq before giving up and returning 503 AI_SERVICE_ERROR. Everything else on the platform — posts, media, analytics — is unaffected; AI is an optional add-on, not a dependency of the core publishing flow.

Can I run multiple platforms from one BlogCore instance?

Yes — that's the entire point. Every table is scoped by platform_id and enforced by a query-level scope, so platforms can't see or affect each other's data even though they share one database and one deployment.

How do webhooks retry on failure?

Up to 3 attempts with backoff: 1 minute, 10 minutes, then 1 hour. After 10 consecutive failures, the webhook is automatically deactivated (is_active: false) — check that field if deliveries seem to have stopped.

Is post content stored as HTML or Markdown?

Either — set content_format to html or markdown per post. Store whichever your editor produces; BlogCore doesn't convert between them, so render each post according to its own content_format value on the way out.

Can I search posts by content, not just title/excerpt?

The built-in search query parameter matches title and excerpt only, not full post body. For full-text search across content, sync published posts into a dedicated search index (Meilisearch, Algolia, Postgres full-text) using the post.published / post.updated webhooks to keep it current.

How is the API secret stored?

As a bcrypt hash — the same way BlogCore would store a password. The plaintext is shown to you exactly once, at creation time, and is never recoverable afterward. If you lose it, revoke the key and issue a new one.

How do I test webhooks locally?

Expose your local dev server with a tunnel (ngrok, Cloudflare Tunnel, or similar) and register that public URL as the webhook target. Trigger a real event (publish a test post) and inspect the delivery in your tunnel's request log.