Rykon AI Docs
Put agents to work from your own code
One REST API for runs, agents, approvals, the record and kill switches. JSON in, JSON out, a scoped key per integration, and an error that says what to change.
Before the hosted endpoint opens
What you can build
Quickstart
From no key to a finished run you have read.
Make an API key
In the console, open API keys and make a key. Only an owner or an admin can. Give it just the scopes this integration needs:
runs:writeto start runs,runs:readto read them.The key is shown once. Put it in your server's environment; if it is ever lost, revoke it and make another.
Terminal# Keep it in your server's environment, never in a browser or a repository export RYKON_AI_KEY="rai_live_..."Start a run
Describe the task in
prompt, and name an agent to run it with that agent's brief, tools and level. The answer is201with the run, queued. It starts within seconds, and anything that needs code, a shell or files gets a fresh sandbox of its own.More in Runs and transcripts.
POST/v1/runscurl -X POST https://api.rykon.ai/v1/runs \ -H "Authorization: Bearer $RYKON_AI_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.", "agentId": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35", "maxTurns": 8, "deadlineSeconds": 900 }'Response201 Created{ "run": { "id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40", "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18", "state": "queued", "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.", "model": "claude-sonnet-5", "max_turns": 8, "deadline_seconds": 900, "sandbox_driver": "kubernetes", "sandbox_addr": null, "created_by": "k7m2q9xd", "created_at": "2026-10-30T14:02:11.408Z", "started_at": null, "deadline_at": null, "finished_at": null, "stopped_by": null, "result": null, "failure_reason": null, "exit_code": null, "num_turns": null, "model_calls": 0, "input_tokens": "0", "output_tokens": "0", "cost_usd": "0", "reported_cost_usd": null, "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35" } }Read the result
Poll the run until
stateisfinished,failedorstopped. A finished run carries itsresult, turns, model calls, tokens and cost; a failed one says why infailure_reason.If the agent asked to do something above its level, the run waits for a person in the console. Levels and approvals explains.
GET/v1/runs/{id}curl https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40 \ -H "Authorization: Bearer $RYKON_AI_KEY"Response200 OK{ "run": { "id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40", "tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18", "state": "finished", "prompt": "Read the three supplier quotes in the brief and record the cheapest per unit, with the quote it came from.", "model": "claude-sonnet-5", "max_turns": 8, "deadline_seconds": 900, "sandbox_driver": "kubernetes", "sandbox_addr": "10.42.3.17", "created_by": "k7m2q9xd", "created_at": "2026-10-30T14:02:11.408Z", "started_at": "2026-10-30T14:02:13.120Z", "deadline_at": "2026-10-30T14:17:13.120Z", "finished_at": "2026-10-30T14:02:49.877Z", "stopped_by": null, "result": "Recorded: Northgate Supply, $4.18 per unit (quote 2 of 3).", "failure_reason": null, "exit_code": 0, "num_turns": 3, "model_calls": 3, "input_tokens": "9412", "output_tokens": "611", "cost_usd": "0.024934", "reported_cost_usd": null, "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35" } }
The reference
58 routes in 11 groups, also as OpenAPI 3.1.