API reference
The Rykon AI API
A REST API over HTTPS. Requests and responses are JSON, every request is authenticated with a scoped API key, and every error has the same shape. The reference below is drawn from one table of the control plane's routes, so it lists exactly what the API answers: 58 routes in 11 groups.
Base URL: https://api.rykon.ai. Send your key as Authorization: Bearer rai_live_.... Each route names the scope its key must hold. Read Authentication, Errors and Pagination once; they apply to everything here. The whole API is also published as OpenAPI 3.1.
The hosted endpoint is not open yet
https://api.rykon.ai opens with the hosted service; until then nothing answers there.curl https://api.rykon.ai/v1/runs \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"error": "forbidden",
"message": "this key does not hold runs:write",
"detail": { "key": "k7m2q9xd", "required": "runs:write" },
"requestId": "req-3f1"
}6 routes
Runs
Start a task, answered directly or in a fresh sandbox, follow its transcript, read its result and cost, and stop it.
/v1/runsStart a run
Queues one task to run once. It is answered directly by the control plane, which runs no model code, unless lane is sandbox; an agent that holds workspace_start hands work that needs code, a shell, files or packages to a fresh sandbox of its own, as a child run. Name an agent to run it with that agent’s brief, model, tools and autonomy level; without one it is a bare task, governed as L0 with only record_finding. The run starts queued, then running, then ends in exactly one of finished, failed (with failure_reason) or stopped. A run under an engaged kill switch is refused (409 refused, naming the switch), and so is a deadline over the account’s maximum (3,600 seconds unless set otherwise) or an archived agent.
Body
- promptstringrequired
- The task: what should happen and what done looks like. 1 to 20,000 characters.
- agentIdstring (uuid)optional
- An agent on this account. The run uses the agent’s model, and naming a different model is refused.
- modelstringoptional
- For a bare run: claude-sonnet-5 (the default), claude-opus-5 or claude-haiku-4-5.
- maxTurnsintegeroptional
- The most model turns the run may take, 1 to 100. Default 8.
- deadlineSecondsintegeroptional
- How long the run may take before it is stopped and failed as deadline exceeded. At least 5; default 900.
- lanestringoptional
- direct (the default): answered by the control plane, which runs no model code. sandbox: the whole run in a fresh sandbox of its own, for work that needs code, a shell or files from the start. On an account under strict isolation every run is a sandbox run, and naming direct is refused (409); the run’s isolation_policy says which policy it ran under.
curl -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
}'{
"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"
}
}/v1/runsList runs
The account’s runs, newest first. Filter by state. Cost is in US dollars as a decimal string, summed from the model calls the relay priced.
Query parameters
- state'queued' | 'running' | 'finished' | 'failed' | 'stopped'optional
- Only runs in this state.
- limitintegeroptional
- 1 to 200. Default 50.
curl "https://api.rykon.ai/v1/runs?state=finished&limit=20" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"runs": [
{
"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"
}
]
}/v1/runs/{id}Get a run
One run: its state, result or failure reason, turns, model calls, tokens and cost. Poll it, or follow its events, to see a run finish.
Path parameters
- idstring (uuid)required
- The run's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"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"
}
}/v1/runs/{id}/eventsRead a run’s transcript
The run’s transcript as events in order: what the model said, the tools it called and their answers, calls waiting for a person, and the result. Read it in pages with after, passing the id of the last event you have; a run that is still running grows at the end. Anything shaped like a token or key is redacted before an event is stored.
Path parameters
- idstring (uuid)required
- The run's id. An id from another account answers 404, exactly like one that does not exist.
Query parameters
- afterstringoptional
- Only events after this event id. Default 0, the start.
- limitintegeroptional
- 1 to 1,000. Default 500.
curl "https://api.rykon.ai/v1/runs/1/events?after=0&limit=500" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"events": [
{
"id": "1",
"kind": "system/egress_gate",
"body": {
"waitedMs": 412
},
"created_at": "2026-10-30T14:02:13.902Z"
},
{
"id": "2",
"kind": "assistant",
"body": {
"message": {
"content": [
{
"type": "text",
"text": "Comparing the three quotes per unit."
}
]
}
},
"created_at": "2026-10-30T14:02:19.640Z"
},
{
"id": "3",
"kind": "tool/answer",
"body": {
"tool": "record_finding",
"state": "done"
},
"created_at": "2026-10-30T14:02:31.903Z"
},
{
"id": "4",
"kind": "result/success",
"body": {
"result": "Recorded: Northgate Supply, $4.18 per unit (quote 2 of 3).",
"num_turns": 3
},
"created_at": "2026-10-30T14:02:49.811Z"
}
]
}/v1/runs/{id}/tool-callsList a run’s tool calls
Every tool the run asked to use and what was decided: allowed (within the agent’s level, run at once), approval (waited for a person) or refused. input is what the agent asked for; final_input is what ran, which differs when a person edited the action.
Path parameters
- idstring (uuid)required
- The run's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/runs/e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57/tool-calls \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"toolCalls": [
{
"id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"call_key": "toolu_01HqK3",
"tool": "record_finding",
"risk": "R0",
"autonomy": "L0",
"input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"final_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"decision": "approval",
"decision_reason": "the agent's rules ask a person for this tool",
"state": "done",
"result": {
"recorded": true
},
"error": null,
"created_at": "2026-10-30T14:02:31.774Z",
"finished_at": "2026-10-30T14:03:52.180Z"
}
]
}/v1/runs/{id}/stopStop a run
Stops a queued or running run. It makes no further model or tool call; any sandbox work it started is stopped too, its token stops working on the sandbox’s next request and the sandbox is removed. stopped is false when the run had already ended, which is not an error. To stop every run of an agent, or the whole account, engage a kill switch instead.
Path parameters
- idstring (uuid)required
- The run's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40/stop \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"run": {
"id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"state": "stopped",
"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": "k7m2q9xd",
"result": null,
"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"
},
"stopped": true
}/v1/toolsList the tool catalogue
Every tool an agent can be given, with its risk class, and the autonomy levels with the highest class each may take without asking. Tools run in Rykon AI’s control plane, never in the sandbox. R4 always waits for a person, whatever the level.
curl https://api.rykon.ai/v1/tools \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"tools": [
{
"name": "record_finding",
"description": "Record one finding in the run record.",
"category": "report",
"risk": "R0",
"kind": "database",
"params": {
"finding": {
"type": "string",
"description": "The finding",
"maxLength": 2000
}
}
},
{
"name": "list_findings",
"description": "List the findings this run has recorded so far.",
"category": "read",
"risk": "R0",
"kind": "database",
"params": {}
}
],
"riskClasses": [
"R0",
"R1",
"R2",
"R3",
"R4"
],
"autonomyLevels": {
"L0": {
"description": "observe: reads and reports only, everything else waits for a person",
"ceiling": "R0"
},
"L1": {
"description": "prepare: may also draft",
"ceiling": "R1"
},
"L2": {
"description": "act inside: may also make reversible changes in the customer's own systems",
"ceiling": "R2"
},
"L3": {
"description": "act outward: may also reach known people and publish",
"ceiling": "R3"
},
"L4": {
"description": "operate: as L3 in v1 (R4 always waits, D11)",
"ceiling": "R3"
}
},
"defaultLevel": "L0",
"alwaysApproval": [
"R4"
]
}/v1/agentsCreate an agent
Creates an agent. It starts at L0, the most careful level; creating one at any other level also needs agents:autonomy, which owners and admins hold. Tools must be in the catalogue. requireApproval names tools that always wait for a person for this agent, whatever their class: a rule can only add approval, never remove it. Unknown fields are refused.
Body
- namestringrequired
- 1 to 100 characters.
- briefstringoptional
- The agent’s role and rules, added to every run’s instructions. Up to 20,000 characters.
- toolsstring[]optional
- Tool names from the catalogue.
- requireApprovalstring[]optional
- Tools that always wait for a person for this agent.
- autonomy'L0' | 'L1' | 'L2' | 'L3' | 'L4'optional
- How far it may act on its own. Default L0. Anything else needs agents:autonomy.
- modelstringoptional
- claude-sonnet-5 (the default), claude-opus-5 or claude-haiku-4-5.
- ownerMemberIdstring (uuid) | nulloptional
- The member responsible for it. Defaults to the person making it, or none for a key.
curl -X POST https://api.rykon.ai/v1/agents \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Supplier analyst",
"brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
"tools": [
"record_finding",
"list_findings"
],
"requireApproval": [],
"autonomy": "L0",
"model": "claude-sonnet-5"
}'{
"agent": {
"id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"name": "Supplier analyst",
"brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
"tools": [
"record_finding",
"list_findings"
],
"require_approval": [],
"autonomy": "L0",
"model": "claude-sonnet-5",
"owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"status": "active",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-10-30T13:40:02.511Z",
"updated_at": "2026-10-30T13:40:02.511Z",
"archived_at": null
}
}/v1/agentsList agents
The account’s agents, newest first.
Query parameters
- status'active' | 'archived'optional
- Only agents in this state.
- limitintegeroptional
- 1 to 200. Default 100.
curl "https://api.rykon.ai/v1/agents?status=active" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"agents": [
{
"id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"name": "Supplier analyst",
"brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
"tools": [
"record_finding",
"list_findings"
],
"require_approval": [],
"autonomy": "L0",
"model": "claude-sonnet-5",
"owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"status": "active",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-10-30T13:40:02.511Z",
"updated_at": "2026-10-30T13:40:02.511Z",
"archived_at": null
}
]
}/v1/agents/{id}Get an agent
One agent, with its brief, tools, rules, level and model.
Path parameters
- idstring (uuid)required
- The agent's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/agents/8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"agent": {
"id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"name": "Supplier analyst",
"brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
"tools": [
"record_finding",
"list_findings"
],
"require_approval": [],
"autonomy": "L0",
"model": "claude-sonnet-5",
"owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"status": "active",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-10-30T13:40:02.511Z",
"updated_at": "2026-10-30T13:40:02.511Z",
"archived_at": null
}
}/v1/agents/{id}Change an agent
Changes any of the agent’s fields; leave out what stays. Changing its autonomy level also needs agents:autonomy. The agent is read fresh on every tool call, so lowering a level or adding a rule applies to the next call of a run already in progress. Every change is on the record.
Path parameters
- idstring (uuid)required
- The agent's id. An id from another account answers 404, exactly like one that does not exist.
Body
- namestringoptional
- 1 to 100 characters.
- briefstringoptional
- Up to 20,000 characters.
- toolsstring[]optional
- Replaces the list.
- requireApprovalstring[]optional
- Replaces the list.
- autonomy'L0' | 'L1' | 'L2' | 'L3' | 'L4'optional
- Needs agents:autonomy to change.
- modelstringoptional
- The model its next runs use.
- ownerMemberIdstring (uuid) | nulloptional
- The member responsible for it.
curl -X PATCH https://api.rykon.ai/v1/agents/8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35 \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"requireApproval": [
"record_finding"
]
}'{
"agent": {
"id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"name": "Supplier analyst",
"brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
"tools": [
"record_finding",
"list_findings"
],
"require_approval": [
"record_finding"
],
"autonomy": "L0",
"model": "claude-sonnet-5",
"owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"status": "active",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-10-30T13:40:02.511Z",
"updated_at": "2026-10-30T14:20:44.019Z",
"archived_at": null
}
}/v1/agents/{id}/archiveArchive an agent
Archives an agent so no new run can use it. Agents are never deleted: the record names them.
Path parameters
- idstring (uuid)required
- The agent's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/agents/8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35/archive \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"agent": {
"id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"name": "Supplier analyst",
"brief": "You compare supplier quotes for the operations team. Record each finding with the quote it came from. Never contact anyone.",
"tools": [
"record_finding",
"list_findings"
],
"require_approval": [],
"autonomy": "L0",
"model": "claude-sonnet-5",
"owner_member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"status": "archived",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-10-30T13:40:02.511Z",
"updated_at": "2026-10-30T13:40:02.511Z",
"archived_at": "2026-10-30T16:01:12.540Z"
}
}5 routes
Approvals
Actions waiting for a person, with the exact input that will run. Read them from code; a person decides them in the console.
/v1/approvalsList approvals
Actions that waited, or are waiting, for a person. proposed_input is what the agent asked for and never changes; action_input is what will run, which a person may edit. An approval expires at the earlier of the approval window and the run’s deadline.
Query parameters
- state'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled'optional
- Only approvals in this state.
- runIdstring (uuid)optional
- Only this run’s approvals.
- limitintegeroptional
- 1 to 200. Default 100.
curl "https://api.rykon.ai/v1/approvals?state=pending" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"approvals": [
{
"id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tool": "record_finding",
"risk": "R0",
"reason": "the agent's rules ask a person for this tool",
"proposed_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"action_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"state": "pending",
"edit_count": 1,
"edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"edited_at": "2026-10-30T14:03:40.002Z",
"decided_by": null,
"decided_at": null,
"decision_note": null,
"expires_at": "2026-10-30T14:17:13.120Z",
"created_at": "2026-10-30T14:02:31.774Z",
"expired": false
}
]
}/v1/approvals/{id}Get an approval
One approval, with the tool, its risk class, why it waited, the action as proposed and as it stands, and who decided it.
Path parameters
- idstring (uuid)required
- The approval's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/approvals/c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"approval": {
"id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tool": "record_finding",
"risk": "R0",
"reason": "the agent's rules ask a person for this tool",
"proposed_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"action_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"state": "pending",
"edit_count": 1,
"edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"edited_at": "2026-10-30T14:03:40.002Z",
"decided_by": null,
"decided_at": null,
"decision_note": null,
"expires_at": "2026-10-30T14:17:13.120Z",
"created_at": "2026-10-30T14:02:31.774Z",
"expired": false
}
}/v1/approvals/{id}Edit an approval’s action
Changes the action a pending approval will run. Only a person signed in to the console can: an API key is refused 403 whatever its scopes, because deciding what an agent may do is a person’s act. The new input is checked against the tool’s parameters; proposed_input keeps what the agent asked for.
A person decides this, in the console. An API key is answered 403 forbidden whatever its scopes. Why
Path parameters
- idstring (uuid)required
- The approval's id. An id from another account answers 404, exactly like one that does not exist.
Body
- inputobjectrequired
- The action as it should run.
- expectEditsintegeroptional
- The edit count you saw. Refused if someone edited it since.
curl -X PATCH https://api.rykon.ai/v1/approvals/c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94 \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"expectEdits": 0
}'{
"approval": {
"id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tool": "record_finding",
"risk": "R0",
"reason": "the agent's rules ask a person for this tool",
"proposed_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"action_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"state": "pending",
"edit_count": 1,
"edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"edited_at": "2026-10-30T14:03:40.002Z",
"decided_by": null,
"decided_at": null,
"decision_note": null,
"expires_at": "2026-10-30T14:17:13.120Z",
"created_at": "2026-10-30T14:02:31.774Z",
"expired": false
}
}/v1/approvals/{id}/approveApprove an action
Runs the action as it stands, once. A person in the console only; an API key is refused 403. Refused once the approval has expired or been decided, or while a kill switch covers the run.
A person decides this, in the console. An API key is answered 403 forbidden whatever its scopes. Why
Path parameters
- idstring (uuid)required
- The approval's id. An id from another account answers 404, exactly like one that does not exist.
Body
- notestringoptional
- A note for the record, up to 2,000 characters.
- expectEditsintegeroptional
- The edit count you saw. Refused if someone edited it since.
curl -X POST https://api.rykon.ai/v1/approvals/c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94/approve \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"note": "Checked against the quotes",
"expectEdits": 1
}'{
"approval": {
"id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tool": "record_finding",
"risk": "R0",
"reason": "the agent's rules ask a person for this tool",
"proposed_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"action_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"state": "approved",
"edit_count": 1,
"edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"edited_at": "2026-10-30T14:03:40.002Z",
"decided_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"decided_at": "2026-10-30T14:03:51.660Z",
"decision_note": "Checked against the quotes",
"expires_at": "2026-10-30T14:17:13.120Z",
"created_at": "2026-10-30T14:02:31.774Z",
"expired": false
}
}/v1/approvals/{id}/rejectReject an action
Ends the action without running it; the agent is told it was rejected, with your note. A person in the console only; an API key is refused 403.
A person decides this, in the console. An API key is answered 403 forbidden whatever its scopes. Why
Path parameters
- idstring (uuid)required
- The approval's id. An id from another account answers 404, exactly like one that does not exist.
Body
- notestringoptional
- Why, for the record and for the agent.
curl -X POST https://api.rykon.ai/v1/approvals/c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94/reject \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"note": "Use the quote dated this month"
}'{
"approval": {
"id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tool": "record_finding",
"risk": "R0",
"reason": "the agent's rules ask a person for this tool",
"proposed_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"action_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"state": "rejected",
"edit_count": 1,
"edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"edited_at": "2026-10-30T14:03:40.002Z",
"decided_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"decided_at": "2026-10-30T14:03:51.660Z",
"decision_note": "Use the quote dated this month",
"expires_at": "2026-10-30T14:17:13.120Z",
"created_at": "2026-10-30T14:02:31.774Z",
"expired": false
}
}/v1/recordRead the record
What the agents did and what was decided, newest first: model calls (model, tokens and cost, never content), tool calls and their results, approval steps, agent changes, kill switches and stopped runs. No route changes or deletes an entry, and the database refuses it too. Page backwards with before, passing next from the previous page; next is null on the last page.
Query parameters
- beforestringoptional
- Only entries before this id: the next value of the previous page.
- runIdstring (uuid)optional
- Only this run.
- agentIdstring (uuid)optional
- Only this agent.
- kindstringoptional
- Only this kind, such as model.call, tool.call, approval.approved or kill_switch.engaged.
- limitintegeroptional
- 1 to 500. Default 100.
curl "https://api.rykon.ai/v1/record?runId=0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40&limit=100" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"entries": [
{
"id": "219",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"kind": "approval.approved",
"actor": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"subject_type": "approval",
"subject_id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
"detail": {
"tool": "record_finding",
"risk": "R0",
"edits": 1
},
"created_at": "2026-10-30T14:03:51.660Z"
},
{
"id": "214",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"kind": "model.call",
"actor": "run:0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"subject_type": "run",
"subject_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"detail": {
"model": "claude-sonnet-5",
"input_tokens": 3204,
"output_tokens": 188,
"cost_usd": 0.008288
},
"created_at": "2026-10-30T14:02:19.602Z"
}
],
"next": null
}3 routes
Kill switches
Stop one run, one agent or the whole account, at once, and release a switch when it is safe.
/v1/kill-switchesList kill switches
The account’s kill switches, engaged and released.
Query parameters
- engaged'true' | 'false'optional
- true for only the switches engaged now. Default false, every switch.
- limitintegeroptional
- 1 to 500. Default 100.
curl "https://api.rykon.ai/v1/kill-switches?engaged=true" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"killSwitches": [
{
"id": "4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15",
"scope": "agent",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"target_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"reason": "Pausing while we change its brief",
"engaged_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"engaged_by_kind": "tenant",
"engaged_at": "2026-10-30T15:10:05.330Z",
"released_by": null,
"released_at": null
}
]
}/v1/kill-switchesEngage a kill switch
Stops one run, every run of one agent, or every run on the account. While it is engaged, every model and tool call it covers is refused, approved actions do not run, no covered run is created or started, and live runs are stopped in the next sweep, which engaging starts at once. Engaging a switch that is already on answers 200 with created false. A run’s switch is never released: the run is stopped.
Body
- scope'run' | 'agent' | 'tenant'required
- What to stop. tenant is the whole account.
- targetIdstring (uuid)optional
- The run or agent, for those scopes.
- reasonstringrequired
- Why, for the record. 1 to 500 characters.
curl -X POST https://api.rykon.ai/v1/kill-switches \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"scope": "agent",
"targetId": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"reason": "Pausing while we change its brief"
}'{
"killSwitch": {
"id": "4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15",
"scope": "agent",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"target_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"reason": "Pausing while we change its brief",
"engaged_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"engaged_by_kind": "tenant",
"engaged_at": "2026-10-30T15:10:05.330Z",
"released_by": null,
"released_at": null
},
"created": true
}/v1/kill-switches/{id}/releaseRelease a kill switch
Lets work start again. Needs killswitches:release, which owners and admins hold. Runs that were stopped stay stopped; start new ones.
Path parameters
- idstring (uuid)required
- The kill switch's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/kill-switches/4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15/release \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"killSwitch": {
"id": "4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15",
"scope": "agent",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"target_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"reason": "Pausing while we change its brief",
"engaged_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"engaged_by_kind": "tenant",
"engaged_at": "2026-10-30T15:10:05.330Z",
"released_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"released_at": "2026-10-30T15:42:18.007Z"
}
}4 routes
Spend
What the account’s AI costs this month, against a monthly budget the AI gateway enforces.
/v1/spendRead this month’s spend
What the account’s model calls have cost this UTC month, from the cost the AI gateway reported for each call: against the monthly budget, by team, by the model that actually answered (fallback marks a call another model answered), and by day, with the alerts sent and the ceiling the gateway enforces today.
curl https://api.rykon.ai/v1/spend \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"month": "2026-10",
"monthStart": "2026-10-01T00:00:00.000Z",
"resetsAt": "2026-11-01T00:00:00.000Z",
"spentUsd": 6.42,
"spentTodayUsd": 0.88,
"calls": 412,
"unpricedCalls": 0,
"budget": {
"usd": 25,
"autoPause": true,
"percent": 25.7,
"remainingUsd": 18.58,
"state": "ok",
"setBy": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"setAt": "2026-10-31T09:12:40.118Z"
},
"heldBy": null,
"byTeam": [
{
"teamId": "61c0e2a4-7b3f-4d95-8e21-0a9c4f6b2d73",
"name": "Marketing",
"status": "active",
"spentUsd": 4.1,
"calls": 260,
"budgetUsd": 10,
"percent": 41,
"held": false
}
],
"notInATeamUsd": 2.32,
"byModel": [
{
"model": "claude-haiku-4-5",
"servedModel": "claude-haiku-4-5",
"servedProvider": "anthropic",
"fallback": false,
"calls": 400,
"costUsd": 6.1,
"inputTokens": 801200,
"outputTokens": 60110
}
],
"byDay": [
{
"day": "2026-10-31",
"costUsd": 0.88,
"calls": 61
}
],
"alerts": [],
"gateway": {
"dailyCeilingUsd": 5,
"appliedUsdPerDay": 5,
"appliedAt": "2026-10-31T09:12:40.512Z"
},
"company": {
"status": "active",
"pace": "active",
"mode": "active",
"pausedAt": null,
"pausedReason": null,
"pausedBy": null,
"pausedByBudget": false
}
}/v1/spend/stateRead the spend state
The short form: whether the company is Active, Quiet or Paused (by whom, since when), the month’s spend, the budget and whether it is holding new work. Cheap enough to poll.
curl https://api.rykon.ai/v1/spend/state \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"company": {
"status": "paused",
"pace": "active",
"mode": "paused",
"pausedAt": "2026-10-31T10:02:11.003Z",
"pausedReason": "Saving tokens until next month",
"pausedBy": "Ada Lovelace",
"pausedByBudget": false
},
"spentUsd": 6.42,
"budget": {
"usd": 25,
"autoPause": true,
"percent": 25.7
},
"heldBy": null,
"resetsAt": "2026-11-01T00:00:00.000Z"
}/v1/spend/budgetSet the monthly budget
Sets the account’s monthly AI budget in US dollars, or removes it with null. Alerts go to the inbox and to the owners by email at 50%, 80% and 100%, once each. At 100% every model call is refused, first by Rykon AI and then by the AI gateway itself (the account key’s ceiling is lowered to what the month has left), and with autoPause the company pauses. Never available over MCP.
Body
- monthlyUsdnumber | nullrequired
- More than 0 and at most 100000, to the cent; null removes the budget.
- autoPausebooleanoptional
- Pause the company when the budget is used up. Default true.
curl -X PUT https://api.rykon.ai/v1/spend/budget \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"monthlyUsd": 25,
"autoPause": true
}'{
"budget": {
"usd": 25,
"autoPause": true
},
"check": {
"percent": 25.7,
"paused": false,
"ceiling": "unchanged"
}
}/v1/spend/daily-limitSet today’s limit
Sets the daily ceiling the AI gateway enforces on the account’s key (at most 100 USD). When the ceiling is reached every lane waits until midnight UTC, with nothing failed; raising it here ends today’s wait and the teams start again a few minutes apart. Never available over MCP.
Body
- usdnumberrequired
- More than 0 and at most 100.
curl -X PUT https://api.rykon.ai/v1/spend/daily-limit \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"usd": 10
}'{
"dailyUsd": 10,
"applied": 10,
"released": true
}15 routes
Webhooks
Signed webhooks to your own endpoints when a run ends or an approval waits or is decided, every delivery and attempt kept and replayable, and triggers your systems call to start a task.
/v1/webhooksList webhooks
The account’s webhook endpoints with the events each receives, whether it is on, the last four characters of its signing secret and its deliveries over the last 30 days, and the event types there are.
curl https://api.rykon.ai/v1/webhooks \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"webhooks": [
{
"id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"url": "https://hooks.example.com/rykon",
"description": "Our ops channel",
"events": [
"run.finished",
"run.failed",
"approval.waiting"
],
"state": "active",
"disabled_reason": null,
"secret_hint": "...9xQa",
"rotating_until": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:00:00.000Z",
"updated_at": "2026-11-12T09:00:00.000Z",
"deliveries": {
"delivered": 41,
"failed": 0,
"pending": 0,
"last_at": "2026-11-12T10:00:01.120Z"
}
}
],
"events": [
"run.finished",
"run.failed",
"run.stopped",
"approval.waiting",
"approval.decided"
]
}/v1/webhooksAdd a webhook
An https endpoint and the events it receives (or * for all). The signing secret is in this answer only: keep it, and use it to check the webhook-signature of every delivery (the webhooks guide shows how). At most 20 per account.
Body
- urlstringrequired
- An https address on the public internet. Private, loopback and metadata addresses are refused when we send.
- eventsstring[]required
- Any of run.finished, run.failed, run.stopped, approval.waiting, approval.decided, or *.
- descriptionstringoptional
- What it is for, up to 300 characters.
curl -X POST https://api.rykon.ai/v1/webhooks \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/rykon",
"events": [
"run.finished",
"run.failed",
"approval.waiting"
],
"description": "Our ops channel"
}'{
"webhook": {
"id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"url": "https://hooks.example.com/rykon",
"description": "Our ops channel",
"events": [
"run.finished",
"run.failed",
"approval.waiting"
],
"state": "active",
"disabled_reason": null,
"secret_hint": "...9xQa",
"rotating_until": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:00:00.000Z",
"updated_at": "2026-11-12T09:00:00.000Z",
"deliveries": {
"delivered": 41,
"failed": 0,
"pending": 0,
"last_at": "2026-11-12T10:00:01.120Z"
}
},
"secret": "whsec_<shown once>"
}/v1/webhooks/{id}Get a webhook
One webhook endpoint, and why it was turned off if it was.
Path parameters
- idstring (uuid)required
- The webhook's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"webhook": {
"id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"url": "https://hooks.example.com/rykon",
"description": "Our ops channel",
"events": [
"run.finished",
"run.failed",
"approval.waiting"
],
"state": "active",
"disabled_reason": null,
"secret_hint": "...9xQa",
"rotating_until": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:00:00.000Z",
"updated_at": "2026-11-12T09:00:00.000Z",
"deliveries": {
"delivered": 41,
"failed": 0,
"pending": 0,
"last_at": "2026-11-12T10:00:01.120Z"
}
}
}/v1/webhooks/{id}Change a webhook
Change the address, the events or the description, or turn it off and on. Turned back on, it sends what is due; send failed deliveries again with replay.
Path parameters
- idstring (uuid)required
- The webhook's id. An id from another account answers 404, exactly like one that does not exist.
Body
- urlstringoptional
- A new https address.
- eventsstring[]optional
- The events it receives, replacing the list.
- descriptionstringoptional
- What it is for.
- enabledbooleanoptional
- false turns it off; true on again.
curl -X PATCH https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84 \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'{
"webhook": {
"id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"url": "https://hooks.example.com/rykon",
"description": "Our ops channel",
"events": [
"run.finished",
"run.failed",
"approval.waiting"
],
"state": "disabled",
"disabled_reason": "Turned off by a person.",
"secret_hint": "...9xQa",
"rotating_until": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:00:00.000Z",
"updated_at": "2026-11-12T09:00:00.000Z",
"deliveries": {
"delivered": 41,
"failed": 0,
"pending": 0,
"last_at": "2026-11-12T10:00:01.120Z"
}
}
}/v1/webhooks/{id}Remove a webhook
Removes the endpoint; deliveries waiting for it are not sent.
Path parameters
- idstring (uuid)required
- The webhook's id. An id from another account answers 404, exactly like one that does not exist.
curl -X DELETE https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"deleted": true
}/v1/webhooks/{id}/rotate-secretRotate the signing secret
A new secret, in this answer only. For 24 hours every delivery carries signatures by both, so you can change the secret your code checks without missing one.
Path parameters
- idstring (uuid)required
- The webhook's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84/rotate-secret \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"webhook": {
"id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"url": "https://hooks.example.com/rykon",
"description": "Our ops channel",
"events": [
"run.finished",
"run.failed",
"approval.waiting"
],
"state": "active",
"disabled_reason": null,
"secret_hint": "...9xQa",
"rotating_until": "2026-11-13T10:00:00.000Z",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:00:00.000Z",
"updated_at": "2026-11-12T09:00:00.000Z",
"deliveries": {
"delivered": 41,
"failed": 0,
"pending": 0,
"last_at": "2026-11-12T10:00:01.120Z"
}
},
"secret": "whsec_<shown once>"
}/v1/webhooks/{id}/testSend a test
Sends a webhook.test event to this endpoint alone, signed like every delivery, so you can check your endpoint end to end.
Path parameters
- idstring (uuid)required
- The webhook's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84/test \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"deliveryId": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
"eventId": "evt_test_mhd2k8_a1b2c3"
}/v1/webhooks/{id}/deliveriesList a webhook’s deliveries
Its deliveries, newest first, kept 30 days: pending (waiting for its next try), delivering, delivered or failed (after the last retry, or refused for good). Read the next page with before set to next.
Path parameters
- idstring (uuid)required
- The webhook's id. An id from another account answers 404, exactly like one that does not exist.
Query parameters
- state'pending' | 'delivering' | 'delivered' | 'failed'optional
- Only deliveries in this state.
- beforestring (uuid)optional
- The next value of the previous page.
- limitintegeroptional
- 1 to 200. Default 50.
curl "https://api.rykon.ai/v1/webhooks/7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62/deliveries?state=failed" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"deliveries": [
{
"id": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
"webhook_id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"event_id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
"event_type": "run.finished",
"state": "delivered",
"attempts": 1,
"next_attempt_at": null,
"last_status": 200,
"last_error": null,
"delivered_at": "2026-11-12T10:00:01.120Z",
"replay_of": null,
"created_at": "2026-11-12T10:00:00.900Z"
}
],
"next": null
}/v1/webhooks/deliveries/{id}Get a delivery
One delivery with the exact payload sent and every attempt: when, the status your endpoint answered, how long it took, what went wrong, and the first 1,000 characters of its answer.
Path parameters
- idstring (uuid)required
- The delivery's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/webhooks/deliveries/7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"delivery": {
"id": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
"webhook_id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"event_id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
"event_type": "run.finished",
"state": "delivered",
"attempts": 1,
"next_attempt_at": null,
"last_status": 200,
"last_error": null,
"delivered_at": "2026-11-12T10:00:01.120Z",
"replay_of": null,
"created_at": "2026-11-12T10:00:00.900Z",
"payload": {
"id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
"type": "run.finished",
"created_at": "2026-11-12T10:00:00.000Z",
"data": {
"run": {
"id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"state": "finished"
}
}
}
},
"attempts": [
{
"at": "2026-11-12T10:00:01.120Z",
"status": 200,
"ms": 182,
"error": null,
"response": "ok"
}
]
}/v1/webhooks/deliveries/{id}/replaySend a delivery again
Sends the same event again as a new delivery, with the same webhook-id, so a receiver that already has it can ignore it.
Path parameters
- idstring (uuid)required
- The delivery's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/webhooks/deliveries/7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62/replay \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"delivery": {
"id": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
"webhook_id": "3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84",
"event_id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
"event_type": "run.finished",
"state": "pending",
"attempts": 0,
"next_attempt_at": null,
"last_status": 200,
"last_error": null,
"delivered_at": "2026-11-12T10:00:01.120Z",
"replay_of": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
"created_at": "2026-11-12T10:00:00.900Z"
}
}/v1/webhooks/triggersList triggers
Addresses your systems call to start a task for one agent, each with its URL and when it was last called.
curl https://api.rykon.ai/v1/webhooks/triggers \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"triggers": [
{
"id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"name": "New order",
"task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
"state": "active",
"url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"secret_hint": "...Lw2c",
"rotating_until": null,
"last_called_at": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:05:00.000Z"
}
]
}/v1/webhooks/triggersAdd a trigger
A trigger for an agent: a call to its URL, signed with its secret (in this answer only), starts a run of that agent with the task template, the call’s body in place of {{payload}} as content to read, never instructions. Every limit, pause, kill switch and approval applies as to any run.
Body
- agentIdstring (uuid)required
- The agent the trigger starts.
- namestringrequired
- What it is, up to 100 characters.
- taskTemplatestringoptional
- The task, with {{payload}} where the call’s body goes (cut at 8,000 characters).
curl -X POST https://api.rykon.ai/v1/webhooks/triggers \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"name": "New order",
"taskTemplate": "A new order came in. Check it and draft the confirmation:\n{{payload}}"
}'{
"trigger": {
"id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"name": "New order",
"task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
"state": "active",
"url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"secret_hint": "...Lw2c",
"rotating_until": null,
"last_called_at": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:05:00.000Z"
},
"secret": "whsec_<shown once>"
}/v1/webhooks/triggers/{id}Change a trigger
Rename it, change its task, or turn it off and on.
Path parameters
- idstring (uuid)required
- The trigger's id. An id from another account answers 404, exactly like one that does not exist.
Body
- namestringoptional
- A new name.
- taskTemplatestringoptional
- A new task template.
- enabledbooleanoptional
- false refuses every call until it is on again.
curl -X PATCH https://api.rykon.ai/v1/webhooks/triggers/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743 \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'{
"trigger": {
"id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"name": "New order",
"task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
"state": "disabled",
"url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"secret_hint": "...Lw2c",
"rotating_until": null,
"last_called_at": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:05:00.000Z"
}
}/v1/webhooks/triggers/{id}Remove a trigger
Removes it; a call to its URL is refused.
Path parameters
- idstring (uuid)required
- The trigger's id. An id from another account answers 404, exactly like one that does not exist.
curl -X DELETE https://api.rykon.ai/v1/webhooks/triggers/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"deleted": true
}/v1/webhooks/triggers/{id}/rotate-secretRotate a trigger’s secret
A new secret, in this answer only; the old one is accepted for 24 hours more.
Path parameters
- idstring (uuid)required
- The trigger's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/webhooks/triggers/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743/rotate-secret \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"trigger": {
"id": "9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"name": "New order",
"task_template": "A new order came in. Check it and draft the confirmation:\n{{payload}}",
"state": "active",
"url": "https://api.rykon.ai/v1/hooks/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743",
"secret_hint": "...Lw2c",
"rotating_until": null,
"last_called_at": null,
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-11-12T09:05:00.000Z"
},
"secret": "whsec_<shown once>"
}/v1/keysList API keys
The account’s keys, newest first, up to 500. The secret part of a key is never shown again after it is made, and its hash never leaves the database.
curl https://api.rykon.ai/v1/keys \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"keys": [
{
"id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
"name": "Nightly report job",
"prefix": "k7m2q9xd",
"scopes": [
"runs:read",
"runs:write",
"agents:read"
],
"member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-10-30T12:00:41.200Z",
"last_used_at": "2026-10-30T14:02:11.408Z",
"expires_at": "2027-01-28T12:00:41.200Z",
"revoked_at": null,
"revoked_by": null
}
]
}/v1/keysMake an API key
Makes a key and returns it once, in token. Store it then; it cannot be shown again. A key may hold only scopes the caller holds itself, so no key can make a broader one. A key a person makes belongs to them and stops working if they leave the account.
Body
- namestringrequired
- What it is for, 1 to 200 characters.
- scopesstring[]required
- At least one scope, each one you hold; a key may hold every tenant scope. Too many or an unknown one is refused, never trimmed.
- expiresInDaysintegeroptional
- 1 to 365. Without it the key lasts until revoked.
curl -X POST https://api.rykon.ai/v1/keys \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Nightly report job",
"scopes": [
"runs:read",
"runs:write",
"agents:read"
],
"expiresInDays": 90
}'{
"id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
"prefix": "k7m2q9xd",
"scopes": [
"runs:read",
"runs:write",
"agents:read"
],
"token": "rai_live_k7m2q9xd_EXAMPLEONLYnotarealsecretEXAMPLEONLY"
}/v1/keys/{id}Read an API key
One key: its name, prefix, scopes, who made it, when and from which address it was last used, its expiry, and, for a caller holding audit:read, its own record (what was done to it and what it did, newest first, up to 50; otherwise events is null). Never the secret or its hash. A key of another account answers 404.
Path parameters
- idstring (uuid)required
- The key's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/keys/7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"key": {
"id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
"name": "Nightly report job",
"prefix": "k7m2q9xd",
"scopes": [
"runs:read",
"runs:write",
"agents:read"
],
"member_id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"created_at": "2026-10-30T12:00:41.200Z",
"last_used_at": "2026-10-30T14:02:11.408Z",
"last_used_ip": "10.42.1.9",
"expires_at": "2027-01-28T12:00:41.200Z",
"revoked_at": null,
"revoked_by": null,
"expired": false,
"member": {
"id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"email": "dana@northwind.example",
"name": "Dana Reyes",
"removed": false
}
},
"events": [
{
"id": "87",
"actor_kind": "tenant",
"actor_id": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"action": "key.mint",
"target_type": "api_key",
"target_id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
"outcome": "allowed",
"detail": {
"prefix": "k7m2q9xd",
"scopes": [
"runs:read",
"runs:write",
"agents:read"
],
"name": "Nightly report job"
},
"created_at": "2026-10-30T12:00:41.200Z"
}
],
"maxScopes": 28,
"maxExpiryDays": 365
}/v1/keys/{id}Change an API key
Renames a key, replaces the set of scopes it holds, or changes when it expires. It applies from the key’s next request. A scope being added must be one the caller holds itself, and never an operator scope; removing is always allowed. A revoked or expired key cannot be changed. Every change is in the audit log as key.update with the key before and after.
Path parameters
- idstring (uuid)required
- The key's id. An id from another account answers 404, exactly like one that does not exist.
Body
- namestringoptional
- 1 to 200 characters.
- scopesstring[]optional
- The whole set the key should hold afterwards, at least one.
- expiresInDaysinteger | nulloptional
- 1 to 365 days from now, or null for no expiry.
curl -X PATCH https://api.rykon.ai/v1/keys/7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71 \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"scopes": [
"runs:read",
"runs:write",
"agents:read",
"record:read"
],
"expiresInDays": 30
}'{
"id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
"prefix": "k7m2q9xd",
"name": "Nightly report job",
"scopes": [
"runs:read",
"runs:write",
"agents:read",
"record:read"
],
"expires_at": "2026-11-30T12:00:41.200Z",
"added": [
"record:read"
],
"removed": []
}/v1/keys/{id}/revokeRevoke an API key
Revokes a key. It fails on its very next request: keys are read on every request and never cached. Revoking one already revoked answers the same.
Path parameters
- idstring (uuid)required
- The key's id. An id from another account answers 404, exactly like one that does not exist.
curl -X POST https://api.rykon.ai/v1/keys/7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71/revoke \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
"prefix": "k7m2q9xd",
"revoked": true
}/v1/membersList members
The people on the account and their roles: owner, admin, member or viewer.
curl https://api.rykon.ai/v1/members \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"members": [
{
"id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"issuer": "https://id.rykon.ai/application/o/rykon-ai/",
"subject": "8c41f0e2a9b7",
"email": "dana@northwind.example",
"name": "Dana Reyes",
"role": "owner",
"created_at": "2026-10-30T11:58:02.144Z",
"last_seen_at": "2026-10-30T14:01:55.900Z"
}
]
}/v1/members/{id}Get a member
One person on the account. A person who was removed answers 409.
Path parameters
- idstring (uuid)required
- The member's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/members/2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"issuer": "https://id.rykon.ai/application/o/rykon-ai/",
"subject": "8c41f0e2a9b7",
"email": "dana@northwind.example",
"name": "Dana Reyes",
"role": "owner",
"created_at": "2026-10-30T11:58:02.144Z",
"last_seen_at": "2026-10-30T14:01:55.900Z"
}/v1/members/{id}Change a member’s role
Changes a person’s role. Only an owner may change an owner or an admin, or make one; a key acts as an admin, never an owner. An account always keeps at least one owner.
Path parameters
- idstring (uuid)required
- The member's id. An id from another account answers 404, exactly like one that does not exist.
Body
- role'owner' | 'admin' | 'member' | 'viewer'required
- The new role.
curl -X PATCH https://api.rykon.ai/v1/members/2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28 \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"role": "viewer"
}'{
"id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"role": "viewer"
}/v1/members/{id}Remove a member
Removes a person from the account and revokes every key they made, in the same step. The last owner cannot be removed. The record of what they did stays.
Path parameters
- idstring (uuid)required
- The member's id. An id from another account answers 404, exactly like one that does not exist.
curl -X DELETE https://api.rykon.ai/v1/members/2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28 \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"removed": true,
"keysRevoked": 1
}/v1/tenantGet the account
The account the key belongs to: its name, plan, status and isolation (shared sandbox nodes, or a dedicated machine).
curl https://api.rykon.ai/v1/tenant \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"slug": "northwind-4k9mq2",
"name": "Northwind",
"isolation": "shared",
"plan": "trial",
"status": "active",
"created_at": "2026-10-30T11:58:02.144Z"
}/v1/tenantRename the account
Changes the account’s name, which is all that can be changed about it here. tenant:write is held only by owners.
Body
- namestringrequired
- 2 to 200 characters.
curl -X PATCH https://api.rykon.ai/v1/tenant \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Northwind Trading"
}'{
"id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"slug": "northwind-4k9mq2",
"name": "Northwind Trading"
}/v1/tenant/closeClose the account
Asks for the account to close. confirm_name must be the account’s name exactly. Nothing changes for 7 days, and every owner is told by email; then the account stops, every key, connection and machine registered to it and its AI gateway key are revoked, and its data is erased: agents, runs and transcripts, tasks, knowledge, connections, mail inboxes and people are deleted, and the audit log and the record keep only what happened and when, with no personal data. Owners only (tenant:write). 409 when the name does not match or a closing is already set.
Body
- confirm_namestringrequired
- The account’s name, exactly.
curl -X POST https://api.rykon.ai/v1/tenant/close \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"confirm_name": "Northwind"
}'{
"close_requested_at": "2026-11-05T09:00:00.000Z",
"close_after": "2026-11-12T09:00:00.000Z",
"grace_days": 7
}/v1/tenant/closeKeep the account
Withdraws a closing before its date. Nothing was deleted, and every owner is told by email. 409 when no closing is set or it has begun.
curl -X DELETE https://api.rykon.ai/v1/tenant/close \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"close_requested_at": null,
"close_after": null
}/v1/tenant/exportExport everything
Everything the account holds, as one gzipped tar (application/gzip): manifest.json (when, the account, each table’s row count, the columns left out, and the audit log’s and record’s chain heads), README.txt, account.json and data/<table>.jsonl, one JSON object per row, for every table that holds the account’s rows. Secrets (sealed credentials, and the hashes keys and tokens are checked against) are never included. Owners and admins; never over MCP. The response example is manifest.json.
curl https://api.rykon.ai/v1/tenant/export \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"format": "rykon-ai-export/1",
"exported_at": "2026-11-05T09:00:00.000Z",
"account": {
"id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"name": "Northwind",
"slug": "northwind-4k9mq2"
},
"tables": {
"agents": 3,
"runs": 41,
"run_events": 512,
"audit_events": 96,
"record_entries": 220,
"members": 2
},
"omitted_columns": {
"api_keys": [
"token_sha256"
]
},
"chains": {
"audit_events": {
"rows": 96,
"head_seq": "18211",
"head_sha256": "9f2c…"
}
}
}/v1/tenant/retentionRead the retention periods
The periods the privacy policy publishes, as the control plane enforces them: the grace period before a closing account is erased, how long after removal a person’s details are erased, and how long finished background jobs are kept.
curl https://api.rykon.ai/v1/tenant/retention \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"close_grace_days": 7,
"removed_member_days": 30,
"finished_job_days": 90
}/v1/tenant/run-isolationRead the run isolation policy
Standard (the default: simple messages are answered directly and a sandbox starts only for code, a shell or files) or Strict (every run, plain replies included, in a sandbox), any per-role overrides, whether a contract locks it to Strict, and whether Strict is available on this account and why not.
curl https://api.rykon.ai/v1/tenant/run-isolation \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"mode": "strict",
"locked": false,
"locked_reason": null,
"strict_available": true,
"strict_unavailable_reason": null,
"roles": {
"researcher": "standard"
},
"effect": {
"strict": "Replies take a few seconds longer and use more compute, because every run starts a sandbox.",
"standard": "Simple messages are answered directly; a sandbox is used only for code, a shell or files."
},
"updated_at": "2026-11-02T09:14:03.120Z",
"updated_by": "Ada Lovelace"
}/v1/tenant/run-isolationChange the run isolation policy
Sets the account’s mode, the per-role overrides, or both. roles replaces the whole map; a role left out follows the account. An unknown role is 409. Strict needs a paid plan (or a dedicated account), else 403 with the reason; an account whose contract locks it to Strict cannot loosen it here (403). Owners and admins; never available over MCP.
Body
- mode'standard' | 'strict'optional
- The account’s mode.
- rolesobjectoptional
- Role key to standard or strict, at most 200; replaces the map whole.
curl -X PUT https://api.rykon.ai/v1/tenant/run-isolation \
-H "Authorization: Bearer $RYKON_AI_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "strict",
"roles": {
"researcher": "standard"
}
}'{
"mode": "strict",
"locked": false,
"locked_reason": null,
"strict_available": true,
"strict_unavailable_reason": null,
"roles": {
"researcher": "standard"
},
"effect": {
"strict": "Replies take a few seconds longer and use more compute, because every run starts a sandbox.",
"standard": "Simple messages are answered directly; a sandbox is used only for code, a shell or files."
},
"updated_at": "2026-11-02T09:14:03.120Z",
"updated_by": "Ada Lovelace"
}/v1/auditRead the audit log
Who did what to the account, newest first: sign-ups, keys made and revoked, role changes, and every request that was refused, with the reason. Append only. Page backwards with before, passing next from the previous page.
Query parameters
- beforestringoptional
- Only events before this id: the next value of the previous page.
- limitintegeroptional
- 1 to 500. Default 100.
curl "https://api.rykon.ai/v1/audit?limit=100" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"events": [
{
"id": "88",
"actor_kind": "tenant",
"actor_id": "k7m2q9xd",
"action": "request.refused",
"target_type": null,
"target_id": null,
"outcome": "denied",
"detail": {
"method": "POST",
"route": "/v1/approvals/:id/approve",
"code": "forbidden",
"message": "an approval is decided by a person, through the console (D10)"
},
"created_at": "2026-10-30T14:05:02.311Z"
},
{
"id": "87",
"actor_kind": "tenant",
"actor_id": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"action": "key.mint",
"target_type": "api_key",
"target_id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
"outcome": "allowed",
"detail": {
"prefix": "k7m2q9xd",
"scopes": [
"runs:read",
"runs:write",
"agents:read"
],
"name": "Nightly report job"
},
"created_at": "2026-10-30T12:00:41.200Z"
}
],
"next": "87"
}