REST API

The Tavora REST API exposes every runtime capability under /api/sdk/*. The Go and TypeScript SDKs are thin wrappers — call this API directly from any language that can speak HTTP + multipart

• SSE.

Base URL

https://api.tavora.ai/api/sdk

In development: http://localhost:8080/api/sdk.

Authentication

Every request authenticates via the X-API-Key header. Keys are app-scoped — one key, one app. Mint one in the admin web UI (covered in the platform’s internal docs) and store it via tavora login so the CLI picks it up too.

curl -H "X-API-Key: tvr_your_api_key" \
  https://api.tavora.ai/api/sdk/app

For browser apps, mint short-lived keys via the session-token exchange — see Browser-based chat.

Endpoint surface

App

Method	Path	Description
GET	/app	App metadata
GET	/metrics	Aggregate token / agent / eval metrics

Indexes (RAG containers)

Method	Path	Description
GET	/indexes	List indexes
POST	/indexes	Create an index
GET	/indexes/:id	Get an index
PATCH	/indexes/:id	Update an index
DELETE	/indexes/:id	Delete an index

Documents

Method	Path	Description
POST	/indexes/:id/documents (multipart)	Upload a document
GET	/indexes/:id/documents	List documents in an index
GET	/indexes/:id/documents/:docId	Get a document
GET	/indexes/:id/documents/by-name/:name	Get by name
GET	/indexes/:id/documents/by-name/:name/versions	List versions
DELETE	/indexes/:id/documents/:docId	Soft-delete (or ?hard=true)
GET	/documents	List documents across the app
GET	/documents/:id	Get a document by ID
DELETE	/documents/:id	Soft-delete (or ?hard=true)
POST	/search	Semantic search (chunks)
POST	/indexes/:id/search	Same, scoped to one index

Search accepts result_type: "document" to return one row per document with the best chunk inlined. Documents carry user-supplied provenance via the multipart metadata field; re-uploading with the same name bumps the version (use if_version for optimistic concurrency).

Secret vaults

Method	Path	Description
POST	/secret-vaults	Create a secret vault
GET	/secret-vaults	List secret vaults
GET	/secret-vaults/:id	Get a secret vault
PATCH	/secret-vaults/:id	Update
DELETE	/secret-vaults/:id	Delete
GET	/secret-vaults/:id/secrets	List secrets (redacted)
PUT	/secret-vaults/:id/secrets/:name	Put a secret value
DELETE	/secret-vaults/:id/secrets/:name	Delete a secret

The API never returns plaintext. Tools that need a credential (LLM provider router, MCP auth.tokenRef resolver, Brave search) read the designated app vault internally; the agent’s JS sandbox does not surface a secret() primitive.

Agent sessions (SSE run)

Method	Path	Description
GET	/agents/system-prompt	Inspect the runtime system prompt
POST	/agents	Create an agent session
GET	/agents	List agent sessions
GET	/agents/:id	Get an agent session
DELETE	/agents/:id	Delete an agent session
POST	/agents/:id/run (SSE)	Stream a turn
POST	/agents/:id/input	Resolve a paused input_request

Agent configs + history

Method	Path	Description
GET	/agent-configs	List configs
GET	/agent-configs/:id	Get a config
DELETE	/agent-configs/:id	Delete
PATCH	/agent-configs/:id/settings	Per-agent operator settings (pinned eval suite)
GET	/agent-configs/:id/versions	List immutable version history
GET	/agent-configs/:id/versions/:vid	Get a single version snapshot
POST	/agent-configs/:id/eval-runs	Trigger an advisory eval run
GET	/agent-configs/:id/eval-runs	List advisory eval runs for this agent
GET	/agent-configs/:id/eval-suite	Resolve the agent’s pinned suite

Agents themselves are created and edited through the code-first source path — there’s no POST /agent-configs and no draft / publish / revert.

Code-first source

The tavora CLI uses this surface to author agents from a local folder. Application code rarely calls these directly.

Method	Path	Description
PUT	/source-sync	Upsert dev drafts from a manifest
POST	/source-validate	Server-side validate without persisting
POST	/source-deploy	Promote drafts to a new published version
POST	/source-rename	Rename an agent’s local id
POST	/source-delete	Destroy a code-managed agent (cascades)

Chat + Conversations

Method	Path	Description
POST	/chat/completions	OpenAI-compatible chat (stateless)
POST	/conversations	Create a stored conversation
GET	/conversations	List conversations
GET	/conversations/:id	Get a conversation with messages
DELETE	/conversations/:id	Delete a conversation
POST	/conversations/:id/messages	Send a message

Skills

Method	Path	Description
GET	/skills	List skills
GET	/skills/:id	Get a skill
POST	/skills/validate	Lint a JS skill body
GET	/skills/authoring-guide	Live-generated skill authoring reference (Markdown)

Skills are authored as .js (module) and .md (prompt) files under tavora/agents/<id>/skills/ and arrive via source-sync. The REST surface is read-only.

Scheduled runs

Method	Path	Description
GET	/scheduled-runs	List
POST	/scheduled-runs	Create
GET	/scheduled-runs/:id	Get
PATCH	/scheduled-runs/:id	Update
DELETE	/scheduled-runs/:id	Delete

Evals (advisory, read-only)

Method	Path	Description
GET	/evals	List eval cases
GET	/evals/:id	Get one
GET	/eval-runs	List runs
GET	/eval-runs/:id	Get a run
GET	/eval-suites	List suites
GET	/eval-suites/:id	Get a suite
GET	/eval-suites/:id/versions	List suite versions

Eval cases live as JSON files under tavora/agents/<id>/evals/ and flow through source-sync. Trigger runs per agent via POST /agent-configs/:id/eval-runs above.

Prompt templates

Method	Path	Description
GET	/prompt-templates	List
POST	/prompt-templates	Create
GET	/prompt-templates/:id	Get
PATCH	/prompt-templates/:id	Update
DELETE	/prompt-templates/:id	Delete

Session forensics

Method	Path	Description
GET	/studio/:sessionID	Enriched trace for one session
POST	/studio/:sessionID/replay	Replay from step (SSE)
POST	/studio/:sessionID/analyze	AI fix analysis

Audit log

Method	Path	Description
GET	/audit-log	Filter audit entries (by action, subject, time range)
GET	/audit-log/export	Bulk export as JSON or CSV (SOC2 evidence)

Response format

Successful responses return JSON with the entity directly at the top level:

{
  "id": "doc_abc123",
  "title": "My Document",
  "status": "ready",
  "created_at": "2026-05-11T10:30:00Z"
}

Error format

Errors return a typed shape:

{
  "error": "version_conflict",
  "message": "document was modified",
  "code": "version_conflict",
  "current_version": 5
}

code is a stable machine-readable error code (e.g. "version_conflict", "NOT_FOUND"). Every other top-level field beyond error / message / code is structured detail an SDK or agent can act on programmatically. Common codes:

• version_conflict — 409 on optimistic-concurrency mismatch; carries current_version.
• NOT_FOUND — 404.
• unauthorized — 401 (missing or invalid API key).

The Go and TS SDKs expose AsVersionConflict / asVersionConflict helpers to extract typed fields from these responses.