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

These routes are built and tested in the control plane. The public endpoint at https://api.rykon.ai opens with the hosted service; until then nothing answers there.
Authenticated request
curl https://api.rykon.ai/v1/runs \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Error
403
{
  "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.

POST/v1/runs

Start 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.

Needsruns:writeReturns201 Created

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.
POST/v1/runs
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
  }'
Response
201 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"
  }
}
GET/v1/runs

List 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.

Needsruns:readReturns200 OKPaged by limit

Query parameters

state'queued' | 'running' | 'finished' | 'failed' | 'stopped'optional
Only runs in this state.
limitintegeroptional
1 to 200. Default 50.
GET/v1/runs
curl "https://api.rykon.ai/v1/runs?state=finished&limit=20" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
    }
  ]
}
GET/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.

Needsruns:readReturns200 OK

Path parameters

idstring (uuid)required
The run's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/runs/{id}
curl https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 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"
  }
}
GET/v1/runs/{id}/events

Read 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.

Needsruns:readReturns200 OKPaged by after

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.
GET/v1/runs/{id}/events
curl "https://api.rykon.ai/v1/runs/1/events?after=0&limit=500" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
    }
  ]
}
GET/v1/runs/{id}/tool-calls

List 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.

Needsruns:readReturns200 OK

Path parameters

idstring (uuid)required
The run's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/runs/{id}/tool-calls
curl https://api.rykon.ai/v1/runs/e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57/tool-calls \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
    }
  ]
}
POST/v1/runs/{id}/stop

Stop 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.

Needsruns:writeReturns200 OK

Path parameters

idstring (uuid)required
The run's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/runs/{id}/stop
curl -X POST https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40/stop \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
}

6 routes

Agents

Named agents with a brief, a model, tools from the catalogue and an autonomy level.

GET/v1/tools

List 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.

Needsagents:readReturns200 OK
GET/v1/tools
curl https://api.rykon.ai/v1/tools \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
  ]
}
POST/v1/agents

Create 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.

Needsagents:writeReturns201 Created

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.
POST/v1/agents
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"
  }'
Response
201 Created
{
  "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
  }
}
GET/v1/agents

List agents

The account’s agents, newest first.

Needsagents:readReturns200 OKPaged by limit

Query parameters

status'active' | 'archived'optional
Only agents in this state.
limitintegeroptional
1 to 200. Default 100.
GET/v1/agents
curl "https://api.rykon.ai/v1/agents?status=active" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
    }
  ]
}
GET/v1/agents/{id}

Get an agent

One agent, with its brief, tools, rules, level and model.

Needsagents:readReturns200 OK

Path parameters

idstring (uuid)required
The agent's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/agents/{id}
curl https://api.rykon.ai/v1/agents/8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
  }
}
PATCH/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.

Needsagents:writeReturns200 OK

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.
PATCH/v1/agents/{id}
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"
    ]
  }'
Response
200 OK
{
  "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
  }
}
POST/v1/agents/{id}/archive

Archive an agent

Archives an agent so no new run can use it. Agents are never deleted: the record names them.

Needsagents:writeReturns200 OK

Path parameters

idstring (uuid)required
The agent's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/agents/{id}/archive
curl -X POST https://api.rykon.ai/v1/agents/8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35/archive \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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.

GET/v1/approvals

List 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.

Needsapprovals:readReturns200 OKPaged by limit

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.
GET/v1/approvals
curl "https://api.rykon.ai/v1/approvals?state=pending" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
    }
  ]
}
GET/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.

Needsapprovals:readReturns200 OK

Path parameters

idstring (uuid)required
The approval's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/approvals/{id}
curl https://api.rykon.ai/v1/approvals/c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
  }
}
PATCH/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.

Needsapprovals:writeReturns200 OK

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.
PATCH/v1/approvals/{id}
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
  }'
Response
200 OK
{
  "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
  }
}
POST/v1/approvals/{id}/approve

Approve 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.

Needsapprovals:writeReturns200 OK

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.
POST/v1/approvals/{id}/approve
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
  }'
Response
200 OK
{
  "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
  }
}
POST/v1/approvals/{id}/reject

Reject 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.

Needsapprovals:writeReturns200 OK

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.
POST/v1/approvals/{id}/reject
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"
  }'
Response
200 OK
{
  "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
  }
}

1 route

The record

Every model call, tool call, approval step, agent change and stop, append only.

GET/v1/record

Read 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.

Needsrecord:readReturns200 OKPaged by before and next

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.
GET/v1/record
curl "https://api.rykon.ai/v1/record?runId=0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40&limit=100" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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.

GET/v1/kill-switches

List kill switches

The account’s kill switches, engaged and released.

Needskillswitches:readReturns200 OKPaged by limit

Query parameters

engaged'true' | 'false'optional
true for only the switches engaged now. Default false, every switch.
limitintegeroptional
1 to 500. Default 100.
GET/v1/kill-switches
curl "https://api.rykon.ai/v1/kill-switches?engaged=true" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
    }
  ]
}
POST/v1/kill-switches

Engage 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.

Needskillswitches:writeReturns201 Created

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.
POST/v1/kill-switches
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"
  }'
Response
201 Created
{
  "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
}
POST/v1/kill-switches/{id}/release

Release a kill switch

Lets work start again. Needs killswitches:release, which owners and admins hold. Runs that were stopped stay stopped; start new ones.

Needskillswitches:releaseReturns200 OK

Path parameters

idstring (uuid)required
The kill switch's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/kill-switches/{id}/release
curl -X POST https://api.rykon.ai/v1/kill-switches/4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15/release \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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.

GET/v1/spend

Read 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.

Needsspend:readReturns200 OK
GET/v1/spend
curl https://api.rykon.ai/v1/spend \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
  }
}
GET/v1/spend/state

Read 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.

Needsspend:readReturns200 OK
GET/v1/spend/state
curl https://api.rykon.ai/v1/spend/state \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
}
PUT/v1/spend/budget

Set 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.

Needsspend:writeReturns200 OK

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.
PUT/v1/spend/budget
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
  }'
Response
200 OK
{
  "budget": {
    "usd": 25,
    "autoPause": true
  },
  "check": {
    "percent": 25.7,
    "paused": false,
    "ceiling": "unchanged"
  }
}
PUT/v1/spend/daily-limit

Set 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.

Needsspend:writeReturns200 OK

Body

usdnumberrequired
More than 0 and at most 100.
PUT/v1/spend/daily-limit
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
  }'
Response
200 OK
{
  "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.

GET/v1/webhooks

List 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.

Needswebhooks:readReturns200 OK
GET/v1/webhooks
curl https://api.rykon.ai/v1/webhooks \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
  ]
}
POST/v1/webhooks

Add 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.

Needswebhooks:writeReturns201 Created

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.
POST/v1/webhooks
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"
  }'
Response
201 Created
{
  "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>"
}
GET/v1/webhooks/{id}

Get a webhook

One webhook endpoint, and why it was turned off if it was.

Needswebhooks:readReturns200 OK

Path parameters

idstring (uuid)required
The webhook's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/webhooks/{id}
curl https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
    }
  }
}
PATCH/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.

Needswebhooks:writeReturns200 OK

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.
PATCH/v1/webhooks/{id}
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
  }'
Response
200 OK
{
  "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"
    }
  }
}
DELETE/v1/webhooks/{id}

Remove a webhook

Removes the endpoint; deliveries waiting for it are not sent.

Needswebhooks:writeReturns200 OK

Path parameters

idstring (uuid)required
The webhook's id. An id from another account answers 404, exactly like one that does not exist.
DELETE/v1/webhooks/{id}
curl -X DELETE https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "deleted": true
}
POST/v1/webhooks/{id}/rotate-secret

Rotate 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.

Needswebhooks:writeReturns200 OK

Path parameters

idstring (uuid)required
The webhook's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/webhooks/{id}/rotate-secret
curl -X POST https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84/rotate-secret \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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>"
}
POST/v1/webhooks/{id}/test

Send a test

Sends a webhook.test event to this endpoint alone, signed like every delivery, so you can check your endpoint end to end.

Needswebhooks:writeReturns202 Accepted

Path parameters

idstring (uuid)required
The webhook's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/webhooks/{id}/test
curl -X POST https://api.rykon.ai/v1/webhooks/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84/test \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
202 Accepted
{
  "deliveryId": "7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62",
  "eventId": "evt_test_mhd2k8_a1b2c3"
}
GET/v1/webhooks/{id}/deliveries

List 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.

Needswebhooks:readReturns200 OKPaged by before and 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.
GET/v1/webhooks/{id}/deliveries
curl "https://api.rykon.ai/v1/webhooks/7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62/deliveries?state=failed" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
}
GET/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.

Needswebhooks:readReturns200 OK

Path parameters

idstring (uuid)required
The delivery's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/webhooks/deliveries/{id}
curl https://api.rykon.ai/v1/webhooks/deliveries/7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
    }
  ]
}
POST/v1/webhooks/deliveries/{id}/replay

Send 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.

Needswebhooks:writeReturns202 Accepted

Path parameters

idstring (uuid)required
The delivery's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/webhooks/deliveries/{id}/replay
curl -X POST https://api.rykon.ai/v1/webhooks/deliveries/7d2e4a91-6c3b-4f58-a0e7-1b9c5d3f8a62/replay \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
202 Accepted
{
  "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"
  }
}
GET/v1/webhooks/triggers

List triggers

Addresses your systems call to start a task for one agent, each with its URL and when it was last called.

Needswebhooks:readReturns200 OK
GET/v1/webhooks/triggers
curl https://api.rykon.ai/v1/webhooks/triggers \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
    }
  ]
}
POST/v1/webhooks/triggers

Add 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.

Needswebhooks:writeReturns201 Created

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).
POST/v1/webhooks/triggers
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}}"
  }'
Response
201 Created
{
  "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>"
}
PATCH/v1/webhooks/triggers/{id}

Change a trigger

Rename it, change its task, or turn it off and on.

Needswebhooks:writeReturns200 OK

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.
PATCH/v1/webhooks/triggers/{id}
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
  }'
Response
200 OK
{
  "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"
  }
}
DELETE/v1/webhooks/triggers/{id}

Remove a trigger

Removes it; a call to its URL is refused.

Needswebhooks:writeReturns200 OK

Path parameters

idstring (uuid)required
The trigger's id. An id from another account answers 404, exactly like one that does not exist.
DELETE/v1/webhooks/triggers/{id}
curl -X DELETE https://api.rykon.ai/v1/webhooks/triggers/3f8b1c27-9e4d-4a6b-b5c0-2d7e9a1f6c84 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "deleted": true
}
POST/v1/webhooks/triggers/{id}/rotate-secret

Rotate a trigger’s secret

A new secret, in this answer only; the old one is accepted for 24 hours more.

Needswebhooks:writeReturns200 OK

Path parameters

idstring (uuid)required
The trigger's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/webhooks/triggers/{id}/rotate-secret
curl -X POST https://api.rykon.ai/v1/webhooks/triggers/9a4c2e18-3b7f-4d61-8e05-c6f1a9d2b743/rotate-secret \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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>"
}

5 routes

API keys

Scoped keys for your own code: list, open, make, change and revoke.

GET/v1/keys

List 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.

Needskeys:readReturns200 OK
GET/v1/keys
curl https://api.rykon.ai/v1/keys \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
    }
  ]
}
POST/v1/keys

Make 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.

Needskeys:writeReturns201 Created

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.
POST/v1/keys
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
  }'
Response
201 Created
{
  "id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
  "prefix": "k7m2q9xd",
  "scopes": [
    "runs:read",
    "runs:write",
    "agents:read"
  ],
  "token": "rai_live_k7m2q9xd_EXAMPLEONLYnotarealsecretEXAMPLEONLY"
}
GET/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.

Needskeys:readReturns200 OK

Path parameters

idstring (uuid)required
The key's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/keys/{id}
curl https://api.rykon.ai/v1/keys/7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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
}
PATCH/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.

Needskeys:writeReturns200 OK

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.
PATCH/v1/keys/{id}
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
  }'
Response
200 OK
{
  "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": []
}
POST/v1/keys/{id}/revoke

Revoke 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.

Needskeys:writeReturns200 OK

Path parameters

idstring (uuid)required
The key's id. An id from another account answers 404, exactly like one that does not exist.
POST/v1/keys/{id}/revoke
curl -X POST https://api.rykon.ai/v1/keys/7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71/revoke \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "id": "7d5b2e90-1f6c-4a38-9b0e-4c2a8f6d3e71",
  "prefix": "k7m2q9xd",
  "revoked": true
}

4 routes

Members

The people on the account and their roles.

GET/v1/members

List members

The people on the account and their roles: owner, admin, member or viewer.

Needsmembers:readReturns200 OK
GET/v1/members
curl https://api.rykon.ai/v1/members \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
    }
  ]
}
GET/v1/members/{id}

Get a member

One person on the account. A person who was removed answers 409.

Needsmembers:readReturns200 OK

Path parameters

idstring (uuid)required
The member's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/members/{id}
curl https://api.rykon.ai/v1/members/2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
}
PATCH/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.

Needsmembers:writeReturns200 OK

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.
PATCH/v1/members/{id}
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"
  }'
Response
200 OK
{
  "id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
  "role": "viewer"
}
DELETE/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.

Needsmembers:writeReturns200 OK

Path parameters

idstring (uuid)required
The member's id. An id from another account answers 404, exactly like one that does not exist.
DELETE/v1/members/{id}
curl -X DELETE https://api.rykon.ai/v1/members/2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28 \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "id": "2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
  "removed": true,
  "keysRevoked": 1
}

8 routes

Account

The account itself: its name, plan, isolation and run isolation policy.

GET/v1/tenant

Get the account

The account the key belongs to: its name, plan, status and isolation (shared sandbox nodes, or a dedicated machine).

Needstenant:readReturns200 OK
GET/v1/tenant
curl https://api.rykon.ai/v1/tenant \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
}
PATCH/v1/tenant

Rename the account

Changes the account’s name, which is all that can be changed about it here. tenant:write is held only by owners.

Needstenant:writeReturns200 OK

Body

namestringrequired
2 to 200 characters.
PATCH/v1/tenant
curl -X PATCH https://api.rykon.ai/v1/tenant \
  -H "Authorization: Bearer $RYKON_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind Trading"
  }'
Response
200 OK
{
  "id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
  "slug": "northwind-4k9mq2",
  "name": "Northwind Trading"
}
POST/v1/tenant/close

Close 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.

Needstenant:writeReturns200 OK

Body

confirm_namestringrequired
The account’s name, exactly.
POST/v1/tenant/close
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"
  }'
Response
200 OK
{
  "close_requested_at": "2026-11-05T09:00:00.000Z",
  "close_after": "2026-11-12T09:00:00.000Z",
  "grace_days": 7
}
DELETE/v1/tenant/close

Keep 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.

Needstenant:writeReturns200 OK
DELETE/v1/tenant/close
curl -X DELETE https://api.rykon.ai/v1/tenant/close \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "close_requested_at": null,
  "close_after": null
}
GET/v1/tenant/export

Export 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.

Needstenant:exportReturns200 OK
GET/v1/tenant/export
curl https://api.rykon.ai/v1/tenant/export \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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…"
    }
  }
}
GET/v1/tenant/retention

Read 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.

Needstenant:readReturns200 OK
GET/v1/tenant/retention
curl https://api.rykon.ai/v1/tenant/retention \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "close_grace_days": 7,
  "removed_member_days": 30,
  "finished_job_days": 90
}
GET/v1/tenant/run-isolation

Read 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.

Needstenant:readReturns200 OK
GET/v1/tenant/run-isolation
curl https://api.rykon.ai/v1/tenant/run-isolation \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
}
PUT/v1/tenant/run-isolation

Change 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.

Needsisolation:writeReturns200 OK

Body

mode'standard' | 'strict'optional
The account’s mode.
rolesobjectoptional
Role key to standard or strict, at most 200; replaces the map whole.
PUT/v1/tenant/run-isolation
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"
    }
  }'
Response
200 OK
{
  "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"
}

1 route

Audit log

Who did what to the account, including every refusal, append only.

GET/v1/audit

Read 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.

Needsaudit:readReturns200 OKPaged by before and next

Query parameters

beforestringoptional
Only events before this id: the next value of the previous page.
limitintegeroptional
1 to 500. Default 100.
GET/v1/audit
curl "https://api.rykon.ai/v1/audit?limit=100" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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"
}