Build on Kamaan

Overview

Kamaan gives you two ways to work with your content programmatically:

REST API— a read-only HTTP API for fetching your published articles (and their translations) into a website or app. This is what you use to render your blog.

MCP server— a Model Context Protocol endpoint that lets AI clients like Claude, ChatGPT, and Cursor read, write, and translate your articles conversationally.

Both authenticate with the same Kamaan API key. The REST base URL is:

https://kamaan.io/api/v1

Authentication

Create an API key from Dashboard → Settings → API & MCP. The key is shown once at creation (it looks like sk_live_…) and is never retrievable again, so store it somewhere safe. Send it on every request as a bearer token:

Authorization: Bearer sk_live_your_key_here

Or, equivalently, with the X-API-Key header:

X-API-Key: sk_live_your_key_here

Keys carry read scopes (read:articles, read:sites) for the REST API. A missing or invalid key returns 401. You can verify your key against the self-describing root endpoint, which needs no auth:

curl https://kamaan.io/api/v1/

REST API

All responses are JSON wrapped in an envelope: success responses include "success": true, errors return { "success": false, "error": { "code", "message" } }. Only published articles are ever returned.

Example: render a blog index (Next.js App Router)

// app/blog/page.js
const KAMAAN_KEY = process.env.KAMAAN_API_KEY;
const SITE_ID = process.env.KAMAAN_SITE_ID;

async function getPosts() {
  const res = await fetch(
    `https://kamaan.io/api/v1/sites/${SITE_ID}/articles/?parent_only=true&limit=20`,
    {
      headers: { Authorization: `Bearer ${KAMAAN_KEY}` },
      next: { revalidate: 300 }, // cache 5 min
    }
  );
  const data = await res.json();
  return data.articles ?? [];
}

export default async function Blog() {
  const posts = await getPosts();
  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>
          <a href={`/blog/${p.slug}`}>{p.title}</a>
        </li>
      ))}
    </ul>
  );
}

Example: render a single article

// app/blog/[slug]/page.js
export default async function Post({ params }) {
  const { slug } = await params;
  const res = await fetch(
    `https://kamaan.io/api/v1/sites/${process.env.KAMAAN_SITE_ID}/articles/by-slug/${slug}/`,
    { headers: { Authorization: `Bearer ${process.env.KAMAAN_API_KEY}` } }
  );
  const { article } = await res.json();
  // article.content is your own authored content. If you render it as HTML,
  // sanitize first (e.g. with isomorphic-dompurify) or render markdown via
  // your renderer of choice.
  return (
    <article>
      <h1>{article.title}</h1>
      <Markdown>{article.content}</Markdown>
    </article>
  );
}

The article object

Article endpoints return a curated, render-ready shape. The key fields:

{
  "id": "…",
  "title": "…",
  "slug": "…",
  "content": "…",                // rendered HTML/markdown body
  "excerpt": "…",
  "language": "en",
  "featured_image_url": "…",
  "featured_image_alt": "…",
  "author": { "name": "…", "avatar_url": "…", "bio": "…" },
  "meta_title": "…",
  "meta_description": "…",
  "keywords": ["…"],
  "canonical_url": "…",
  "og_title": "…", "og_description": "…", "og_image": "…",
  "twitter_title": "…", "twitter_description": "…", "twitter_image": "…",
  "table_of_contents": [ … ],
  "reading_time_minutes": 6,
  "faq_schema": { … },           // JSON-LD, ready to embed
  "article_schema": { … },       // JSON-LD, ready to embed
  "published_at": "2026-05-29T…Z",
  "updated_at": "…",
  "parent_article_id": "…",      // set on translations
  "translation_status": "auto_translated",
  "translations": {              // published siblings only
    "es": { "article_id": "…", "slug": "…", "title": "…", "url": "…" }
  },
  "hreflang": [ { "lang": "es", "url": "…" }, … ]
}

The list endpoint returns a trimmed version of this (no content, plusexcerpt for previews). Use translations and hreflang to wire up language switchers and SEO tags automatically. The og_title, og_description, and og_image fields drop straight into your markup. To hand-check the output, our Open Graph tag generator builds the same tags from a title, description, and image.

MCP server

Connect any MCP-compatible client to operate your content with natural language. New to this? The step-by-step setup guide walks through connecting Claude, ChatGPT, or Cursor. The server speaks MCP over Streamable HTTP at:

https://kamaan.io/mcp

Add it to your client config (Claude Desktop shown), authenticating with the same API key:

{
  "mcpServers": {
    "kamaan": {
      "url": "https://kamaan.io/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key_here" }
    }
  }
}

The server exposes these tools to the AI client:

My_Sites          – list your sites
Site_Details      – full config for one site
Browse_Articles   – list a site's articles (filter by language/status)
Read_Article      – read one article in full
Search_Articles   – search by title / focus keyword
Write_Article     – create a new article (markdown)
Edit_Article      – update an existing article
Update_SEO_Fields – update SEO / meta only
Translate_Article – translate an article into one or more languages

So you can say things like “Write a post about X on my main site, then translate it to Spanish and German” and the client will call the right tools for you.

Rate limits

API and MCP calls count toward your plan's monthly call allowance, which resets each billing period. When you exceed it, requests return 429 with a message explaining the limit. You can see your current usage in Dashboard → Settings → Billing. Upgrade for a higher allowance.