API Reference

Base URL

https://api.oxagen.ai/v1

Every path below is a public endpoint. Platform plumbing (session management, billing, tenant provisioning, OAuth data-source connectors, worker webhooks, etc.) is handled by the web app at app.oxagen.ai and is intentionally not part of the public contract.

Authentication

Authorization: Bearer <your-token>

Sign in at app.oxagen.ai and open Settings → API Keys to mint a workspace-scoped bearer token. Each key has a name, a scope set, and can be revoked at any time. Treat the secret like a password — Oxagen displays it once at creation and stores only a hash thereafter.

MCP clients receive credentials directly from the installer.

All requests are workspace-scoped: the token determines which workspace you're reading from and writing to. If you need multiple workspaces, create them in the dashboard and use a distinct token per workspace.

Capability surface — every agent tool as a REST endpoint

Every tool in Agent Tools with api in its surfaces is mounted as a REST endpoint at:

POST /v1/cap/<tool-name>

The agent uses the same set of capabilities through the in-app chat and MCP server; this surface lets your own code reach them without spawning an LLM loop. See Agent Overview for the underlying model.

The request body is the capability's typed input schema. The response is the capability's typed output schema. Both schemas are published in https://api.oxagen.ai/openapi.json and rendered interactively in the API Explorer.

Example — ontology.search

curl -X POST https://api.oxagen.ai/v1/cap/ontology.search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "query": "validateCard",
    "top_k": 20
  }'

Idempotency-Key header — supply any stable UUID. Retries with the same key replay the cached response for 24 hours so you can safely retry on network error without double-charging credits.

A successful call deducts the capability's listed credit cost from the workspace balance and returns the typed output wrapped in an envelope:

{
  "result": { ... },
  "credits_charged": 1,
  "idempotency_key": "<uuid>"
}

credits_charged is the amount deducted from the workspace balance. idempotency_key echoes back the key you supplied (or a server-generated one if you omitted the header). Failures refund the reservation automatically — a failed call costs nothing.

Errors

The capability surface uses the same status codes as the rest of the API (Error Reference below), plus one capability-specific case:

• 402 Payment Required — workspace credit balance is below the capability's credit_cost. The response body includes kind, required, and available so the client can show a precise top-up prompt.

What's not on this surface

Two families never reach the REST surface:

• viz.* rendering tools — they're inline-message renderers in the dashboard chat, not callable APIs.
• Workspace-scoped dynamic capabilities — workspace-defined custom tools dispatched through oxagen.capabilities.dynamic are not mounted as standalone routes; they're reachable through the agent loop only.

Everything else with api · ... in the catalog's Surfaces column is a live endpoint.

Ontology — Knowledge Graph

The typed convenience layer for working with the workspace graph directly — paginated lists, semantic search, and the natural-language prompt endpoint. Use these when you want graph access without threading through a tool name; use the Capability surface above when you want the exact same primitives the agent uses.

Prompt — Add Data or Ask Questions

The prompt endpoint is the easiest way to interact with your knowledge graph. Describe what you know; ask what you want to learn.

# Add something
curl -X POST https://api.oxagen.ai/v1/ontology/prompt \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Alex Kim (alex@fintech.io) is CEO of FinCo. Met today to discuss a $50k enterprise deal."}'

# Ask something
curl -X POST https://api.oxagen.ai/v1/ontology/prompt \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Which enterprise deals are close to closing?"}'

Response includes an answer (for questions) and a nodes_created / edges_created count (for additions).

Semantic Search

curl -X POST https://api.oxagen.ai/v1/ontology/nodes/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "fintech companies I spoke with last month",
    "top_k": 10,
    "mode": "hybrid",
    "filters": {"type": ["organization", "meeting"]}
  }'

mode can be "semantic" (vector-only), "keyword" (text-only), or "hybrid" (both).

List Nodes

curl "https://api.oxagen.ai/v1/ontology/nodes?type=person&limit=20" \
  -H "Authorization: Bearer <token>"

MCP — Model Context Protocol

The MCP endpoint lets Claude, Cursor, VS Code, Windsurf, Codex, or any MCP-compatible client read and write the workspace graph directly. Pair it with the install selector on oxagen.ai for a one-line setup per client.

curl -X POST https://api.oxagen.ai/v1/mcp/token \
  -H "Authorization: Bearer <token>"

Health

Error Reference