Public API

A versioned REST API for your own code: conversations with an agent, attachments, feedback, knowledge search and text pipelines, authenticated by project API keys.

The public API lives under /api/v1 and accepts API keys only. A browser session is never accepted there, and a key is never accepted on the Studio's own endpoints under /api/internal. The two surfaces are kept separate on purpose, and the public one is narrower: building agents, publishing versions and managing members happen in the Studio.

What it exposes

Area	Routes	Scope
Conversations	POST /api/v1/agents/{agentId}/conversations sends a message, in a new conversation or in the one named by conversationId. GET on the same path lists the agent's conversations, GET …/conversations/{conversationId} returns one thread.	full to send, read to list
Streaming	GET …/conversations/{conversationId}/runs/{runId}/stream, as Server-Sent Events	read
Attachments	POST …/conversations/attachments (multipart) deposits a file that a message then cites in attachmentIds. GET …/conversations/attachments/{attachmentId}/download returns a short-lived download URL.	full / read
Feedback	POST …/conversations/{conversationId}/feedback, a score of 1 or -1 and an optional comment	full
Knowledge search	POST /api/v1/knowledge/search starts a search over collections, GET /api/v1/knowledge/search/{searchId} returns its results	read
Pipelines	POST /api/v1/pipelines/execute runs summarize, classify, translate or extract_entities on a text. GET /api/v1/pipelines/results lists the results.	full / read
Sandbox	GET /api/v1/sandbox/requirement reads the instance's sandbox policy, POST /api/v1/sandbox/validate-mcp checks MCP execution in a sandbox	read / full

{agentId} is the agent's UUID. The Headless API card of the agent's Deploy tab shows the full endpoint.

Keys

• A key belongs to a project and carries a scope: read, or full, which also covers the read routes.
• Its prefix sets the environment, rk_live_ or rk_test_, and the agent needs an active API deployment in that same environment. Turning the API switch off on the Deploy tab cuts the agent's /api/v1 traffic, reading included.
• It can be restricted to specific agents, so an integration only reaches what it needs.
• It can carry an expiry date.
• Its full value is shown once, at creation. Rikoo stores only a SHA-256 hash of it.
• Revoking a key takes effect on the next request.

Send it in the Authorization header, with or without the Bearer prefix.

curl -X POST "https://rikoo.example.com/api/v1/agents/$AGENT_ID/conversations" \
  -H "Authorization: Bearer $RIKOO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-question-0001" \
  -d '{"message":"My invoice is wrong","sync":true}'

With "sync": true, the call waits for the run and returns the answer. Without it, the call returns the conversationId and the runId at once, and you follow the run on its stream. The Idempotency-Key header is optional: a retry under the same key gets the same response instead of creating a second turn.

Streaming

The stream of a run is a Server-Sent Events stream of its events: the answer as the model produces it (message.delta), tool calls as they are made, and a terminal event (run.completed, run.failed, run.aborted or run.refused) that closes it. It starts by replaying what the run has already recorded, so a client that connects late or reconnects misses nothing, and long conversations need no poll loop.

The contract is generated from the code

The instance serves its OpenAPI description at /api/openapi.json, with an interactive view at /api/docs. It is generated from the code that serves the routes, not written by hand. The routes under /api/v1 are the public contract.