Developers

REST API

Build with ZainaBot.AI. Same auth, same data model, same tool catalog as the MCP server — exposed as REST.

Auth

Every request needs an Authorization: Bearer zb_pk_* header. Generate keys on the API keys page.

TypeScript SDK

The recommended way to build is the official SDK. Works in Node, browsers, and edge runtimes.

npm install @zainabot/sdk

import { ZainaBot } from '@zainabot/sdk'

const zb = new ZainaBot({ apiKey: process.env.ZAINABOT_API_KEY! })

const { projects } = await zb.projects.list()
const answer = await zb.projects.query(projects[0].id, {
  question: 'What pricing did I commit to in my last call with Acme?',
})
console.log(answer.answer)

View on npm

Endpoints

Tap a path for the example curl. All responses are JSON.

GET/api/v1/coachestap to expand

List active coaches. Optional ?category=Marketing.

curl https://zainabot.ai/api/v1/coaches \
  -H "Authorization: Bearer $ZB_KEY"

GET/api/v1/projectstap to expand

List your active projects.

curl https://zainabot.ai/api/v1/projects \
  -H "Authorization: Bearer $ZB_KEY"

POST/api/v1/projects/{id}/querytap to expand

Cross-source retrieval over a project (sessions + uploaded docs). Returns answer + citations.

curl -X POST https://zainabot.ai/api/v1/projects/PROJECT_ID/query \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"What pricing did I commit to in my last call with Acme?"}'

POST/api/v1/coaches/{id}/chattap to expand

Single-turn chat with a coach. Creates a session, or continues one with session_id.

curl -X POST https://zainabot.ai/api/v1/coaches/COACH_ID/chat \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"How do I debug a slow Postgres query?"}'

GET/api/v1/action-itemstap to expand

List your action items. Filter by ?status=open&project_id=...

curl "https://zainabot.ai/api/v1/action-items?status=open" \
  -H "Authorization: Bearer $ZB_KEY"

POST/api/v1/action-itemstap to expand

Create an action item.

curl -X POST https://zainabot.ai/api/v1/action-items \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"Email Acme about pricing","due_date":"2026-05-16"}'

PATCH/api/v1/action-items/{id}tap to expand

Mark done / dismissed / reopen.

curl -X PATCH https://zainabot.ai/api/v1/action-items/ITEM_ID \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

DELETE/api/v1/action-items/{id}tap to expand

Permanently delete an action item.

curl -X DELETE https://zainabot.ai/api/v1/action-items/ITEM_ID \
  -H "Authorization: Bearer $ZB_KEY"

POST/api/v1/projects/{id}/sessions/attachtap to expand

Attach a chat / practice / live session to a project.

curl -X POST https://zainabot.ai/api/v1/projects/PROJECT_ID/sessions/attach \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"SESSION_ID","session_type":"chat"}'

POST/api/v1/practice-sessionstap to expand

Start a roleplay session. Use the returned session_id with coaches/{id}/chat to play.

curl -X POST https://zainabot.ai/api/v1/practice-sessions \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"coach_id":"COACH_ID"}'

POST/api/v1/workflows/runtap to expand

Run a multi-bot workflow end-to-end. Server executes every step inline. Pro+ plan, ~60s ceiling.

curl -X POST https://zainabot.ai/api/v1/workflows/run \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"blog-to-thread","input":"Why pricing pages lie"}'

GET/api/v1/usagetap to expand

Your plan, monthly token usage + remaining, cost so far, and the rate-limit windows.

curl https://zainabot.ai/api/v1/usage \
  -H "Authorization: Bearer $ZB_KEY"

Rate limits + quota

Per-API-key buckets. Different endpoint classes have different per-minute caps so heavy chat traffic can't starve list calls.

Read (GET /coaches, /projects, /action-items) — 60/min
Write (POST/PATCH/DELETE /action-items, /projects/.../sessions/attach, /practice-sessions) — 60/min
Chat (POST /coaches/.../chat) — 30/min
Query (POST /projects/.../query) — 20/min

Exceeded → HTTP 429 with retryAfter seconds. Chat + query also count against your monthly token quota (Pro 1M, Pro+ 2M, Enterprise 10M); when exhausted, both return 429 with a quota message.

Errors

Non-2xx responses return { "error": "..." }. Common codes:

400 — validation error (missing or malformed field).
401 — missing or empty Authorization header.
403 — key revoked, invalid, or not Pro+.
404 — resource not found or not yours.
429 — rate limit or monthly token quota hit. See above.
502 — upstream model error.

Questions? Open a support ticket →