API Reference

Getting Started

Three steps to your first call. Do it in the dashboard, or with the API:

1. 1.Create an account — POST /v1/auth/register with { email, password }, then confirm the 6-digit code at /v1/auth/verify-email.
2. 2.Create an API key — POST /v1/keys with { "name": "my-app" }, or a service-scoped key with POST /v1/{service}/keys. The brain, memory, llm and pay keys are free to create — you only pay for what you meter.
3. 3.Call the API — pass the key as a bearer token (below). Add prepaid balance any time with POST /v1/billing/topup.

Authentication

Every request takes a bearer token. The base URL for everything is:

Authorization: Bearer $INCORD_KEY
Base URL: https://api.incord.ai

GET /health, GET /v1/cloud/models and GET /v1/cloud/audio/voices are public (no key). Everything else returns 401 without a valid key, 402when your prepaid balance can't cover a metered call or you're over a free quota, and 429 when you exceed your rate limit.

Quickstart

Call any of 128+ models with the OpenAI Chat Completions shape:

curl https://api.incord.ai/v1/cloud/chat/completions \
  -H "Authorization: Bearer $INCORD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "messages": [{ "role": "user", "content": "Say hello in one line." }]
  }'

Or ask the Knowledge API for ranked, real-time context:

curl https://api.incord.ai/v1/search \
  -H "Authorization: Bearer $INCORD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest bitcoin analysis",
    "top_k": 5,
    "filters": { "asset_class": "crypto", "max_age_hours": 24 }
  }'

Knowledge response (truncated):

{
  "query": "latest bitcoin analysis",
  "confidence": { "sufficient": true, "top_rerank_score": 0.94 },
  "counts": { "finance": 5, "commerce": 0, "code": 0 },
  "results": [
    {
      "id": "live:btc_multi_tf_analysis",
      "content": "BTC multi-timeframe technical analysis ...",
      "confidence": 0.95,
      "domain": "finance",
      "node_type": "snapshot",
      "timestamp": 1718700000
    }
  ],
  "scope": "full_brain"
}

Cloud AI — OpenAI-compatible (/v1/cloud)

Drop-in OpenAI shape across 128+ cloud models (Anthropic, OpenAI, Google, Qwen, DeepSeek …) plus embeddings, rerank, audio (TTS/STT), realtime and video generation. Point any OpenAI SDK at api.incord.ai/v1/cloud and set model to any id from /v1/cloud/models — pin an exact model or a tier alias. Billed per token from your prepaid balance (or bundled free under an Agents plan); the first 1,000 grounded calls/month are free. Browse every model at /models.

Voice — real-time voice agents (/v1/voice)

Low-latency phone-style voice over WebRTC: speech-to-text → your agent → text-to-speech, all server-side, one pipeline per call. Built-in mode uses Incord's premium STT/TTS (billed per minute); BYOK lets you plug in your own OpenAI / Deepgram / Cartesia keys (the vendor bills you).

Knowledge — Retrieval API (/v1/search)

One ranked, validated, real-time context call for your agents: embed + hybrid (dense + sparse) retrieval + graph rerank across finance, commerce, code and research, with a confidence signal. Billed as the brain service — the first 5,000 calls/month are free, then $4.99 per 1,000. Free-tier calls are paced at 10/min and 500/day. Reranking is a Brain Pro feature.

Memory — per-user memory (/v1/memory)

Persistent per-user conversation memory + a polymorphic node/edge graph. Store messages, recall the relevant ones, synthesize, and traverse the graph. Provision a memory key first (POST /v1/memory/keys). Billed as the memory service — the first 10,000 calls/month are free, then $1.00 per 1,000; storage is a separate GB quota per tier (writes are blocked over quota, reads stay open).

Agents — hosted agents (/v1/agent)

Long-running, tool-using agents with sessions, files and channels, isolated per tenant. The control API forwards to your tenant's agent daemon. Billed as a monthly Agents subscription with a bundled run allowance — Starter $19/mo (50 runs), Pro $49/mo (200), Scale $199/mo (1,000) — which also bundles brain + memory + LLM usage.

Account, Keys & Billing

Create an account, mint service-scoped keys, and top up a prepaid balance. brain / memory / llm / pay keys are free to create — the meter is the gate; agents keys need an active subscription.

Use the OpenAI SDK

Because the Cloud AI API is OpenAI-shaped, you don't need our SDK — just point base_url at https://api.incord.ai/v1/cloud and use your key.

Python

from openai import OpenAI

client = OpenAI(api_key="$INCORD_KEY", base_url="https://api.incord.ai/v1/cloud")

# Chat — model = any id from /v1/cloud/models
chat = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Summarize today's BTC move."}],
)
print(chat.choices[0].message.content)

# Embeddings
emb = client.embeddings.create(model="qwen3-embedding", input="hello world")
print(len(emb.data[0].embedding))

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.INCORD_KEY, baseURL: "https://api.incord.ai/v1/cloud" });

const chat = await client.chat.completions.create({
  model: "claude-haiku-4-5",
  messages: [{ role: "user", content: "Summarize today's BTC move." }],
});
console.log(chat.choices[0].message.content);

Connect via MCP

The Memory API speaks the Model Context Protocol, so any MCP-aware client (Claude Desktop, Cursor, Windsurf) can read and write your memory. Add this to your client's MCP config:

{
  "mcpServers": {
    "incord": {
      "url": "https://api.incord.ai/v1/memory/mcp",
      "headers": { "Authorization": "Bearer $INCORD_MEMORY_KEY" }
    }
  }
}

For HTTP clients that prefer SSE, point the transport at https://api.incord.ai/v1/memory/mcp/sse. The same bearer token authenticates the JSON-RPC and the stream.

Set up with your AI

In a hurry? Paste the block below into Claude, ChatGPT, or Cursor — it has everything an AI assistant needs to wire Incord into your project for you.

You are setting up the Incord API in my project.

Base URL: https://api.incord.ai
Auth: every request needs the header  Authorization: Bearer <INCORD_KEY>
My key is in the env var INCORD_KEY (ask me if it is missing).

Incord is OpenAI-compatible for the Cloud AI API, so use the official OpenAI SDK
with base_url="https://api.incord.ai/v1/cloud". Key endpoints:
  - Models (public):  GET  /v1/cloud/models
  - Chat:             POST /v1/cloud/chat/completions   model = any id from /v1/cloud/models
  - Embeddings:       POST /v1/cloud/embeddings
  - Knowledge/RAG:    POST /v1/search                   body { query, top_k, filters }
  - Memory:           POST /v1/memory/search            body { user_id, query, top_k }

Tasks:
1. Detect my stack (package.json / requirements.txt / go.mod).
2. Add the OpenAI client configured for base_url="https://api.incord.ai/v1/cloud", reading INCORD_KEY from env.
3. Add one working call to /v1/cloud/chat/completions and one to /v1/search.
4. Print how to run it. Do NOT hardcode the key; use the env var.

Errors

• —401 Unauthorized — missing or invalid API key.
• —402 Payment Required — over a free quota, or prepaid balance can't cover this metered call. Top up with POST /v1/billing/topup.
• —403 Forbidden — email not verified.
• —422 Unprocessable Entity — the request body is missing required fields.
• —429 Too Many Requests — over your rate limit (free tier: 10/min, 500/day). See the Retry-After header.