External KB API

Most of Atender’s Knowledge Base is managed in the in-app editor. But for teams that prefer doc-as-code workflows — the same way they manage application code — Atender exposes a stable, scope-gated v1 API at /api/v1/kb/*. You authenticate with a tenant API key, you call the endpoints, and your KB stays in sync with whatever upstream source of truth you keep.

This is how Atender keeps its own help center current. Articles live as markdown in a vault, a small Python script reads them on every change, and /api/v1/kb/* upserts them into the live KB. Embeddings rebuild server-side automatically.

When to use the API

Reach for the API when:

• Your articles are authored elsewhere — in a Git repo, a CMS, a spreadsheet, another help center. You want a sync, not a copy-paste.
• You want articles versioned and reviewed in pull requests. Markdown in a Git repo gives you diff, branch, review, merge — the same review discipline as code.
• You’re migrating from another help center. A one-time bulk import via the API is faster than recreating articles in the UI.
• You’re building a content pipeline. Generate articles from product specs, sync from a spec repository, regenerate when source data changes.

If your team writes content in the in-app editor and that flow is working, you don’t need the API.

What the API can do

The v1 surface covers the operations a content pipeline needs:

• Articles — List, get, create, update, delete, publish, mark-reviewed
• Categories — List, get, create, update, delete
• Subcategories — List, create, update, delete
• Tags — List, create, update, delete
• Search — Run a query against the live retrieval pipeline (keyword + vector)

The endpoints accept JSON. Articles can be created or updated with full content, summaries, keywords, custom metadata (uxPath, videoUrl, etc.), and category assignments.

What the API can’t do (yet)

• Roles — KB role tagging isn’t yet exposed on the v1 surface. If you need role tagging applied from CI, you’ll fall back to the in-app editor for that step. The v1 endpoints for roles are tracked as a follow-up task.
• Sections — managing sections via API isn’t supported on v1 yet. Use the in-app editor.
• Knowledge Base settings — branding, layout, theme — aren’t on the v1 API. Configure them in the in-app editor.
• Translations — translation jobs are queued automatically when you publish. There’s no API to trigger them manually, and direct write of translated content isn’t supported on v1 yet.
• Handbook procedures — the Handbook has its own internal API (/api/handbook/*) that requires Supabase session auth, not API keys. There’s no external surface for the Handbook today.

Authentication

Every v1 KB call is authenticated with a tenant API key. Generate one in Settings → API Keys:

1. Click New API key.
2. Pick scopes: knowledge:read (for read-only access) and/or knowledge:write (for create/update/delete).
3. Name the key something obvious — “doc-as-code pipeline”, “migration script”, “github-actions-sync”.
4. Save. Copy the key — it’s shown once, then hidden.
5. Set it as Authorization: Bearer <key> on each request.

API keys come in two prefixes:

• sa_live_* — Production keys. Make real changes to the live KB.
• sa_test_* — Sandbox keys. For development and testing.

API keys don’t expire. Rotate them via Settings → API Keys when team members leave or you suspect compromise.

The shape of an article

An article in the API has these fields:

{
  "title": "How to update your payment method",
  "slug": "update-payment-method",
  "summary": "Open your account settings, go to Billing, click Change.",
  "content": "...full markdown body...",
  "categoryId": "cat_abc123",
  "subcategoryId": null,
  "status": "published",
  "difficulty": "beginner",
  "estimatedMinutes": 2,
  "keywords": ["payment", "credit card", "billing"],
  "customMetadata": {
    "uxPath": "Account → Billing → Payment methods"
  }
}

The customMetadata field is an open jsonb bucket — you can stash any structured data your downstream consumers need. Atender’s own pipeline puts uxPath, type, related[], and sourcePath here. The public read API exposes customMetadata so the Agent Stack and other downstream consumers can read it.

How idempotency works

Articles are upserted by slug. Sending the same article twice updates the existing one — there’s no “is this a create or an update?” branching for callers. The same is true for categories (matched by slug), subcategories (matched by categoryId + slug), and tags (matched by slug).

Rate limits

The API has standard rate limits — generous for normal use, reasonable for bulk imports. If you’re bulk-importing a few thousand articles, expect to add backoff between calls. The error response includes a Retry-After header when limits are hit.

A doc-as-code pattern

The pattern Atender’s own help center uses:

1. Articles are markdown files in a Git repo, with frontmatter for metadata.
2. A small Python script reads each file, calls /api/v1/kb/categories to ensure the category exists, then calls /api/v1/kb/articles to upsert the article.
3. Embeddings rebuild server-side as part of the publish path.
4. Translations queue automatically.

If that’s the shape you want, see Push articles via API for a working example.

Where to go next

• Push your first article via API: Push articles via API
• Generate an API key: API keys
• Understand what gets retrieved: KB search and AI retrieval