Rykon AI Docs

Put agents to work from your own code

One REST API for runs, agents, approvals, the record and kill switches. JSON in, JSON out, a scoped key per integration, and an error that says what to change.

Before the hosted endpoint opens

Every route here is built and tested in the control plane, and the console uses the same ones today. The public endpoint opens with the hosted service. The MCP server is built and connects Claude Code, Cursor and Claude Desktop; webhooks tell your code when a run finishes or an approval waits.

What you can build

Quickstart

From no key to a finished run you have read.

  1. Make an API key

    In the console, open API keys and make a key. Only an owner or an admin can. Give it just the scopes this integration needs: runs:write to start runs, runs:read to read them.

    The key is shown once. Put it in your server's environment; if it is ever lost, revoke it and make another.

    Terminal
    # Keep it in your server's environment, never in a browser or a repository
    export RYKON_AI_KEY="rai_live_..."
  2. Start a run

    Describe the task in prompt, and name an agent to run it with that agent's brief, tools and level. The answer is 201 with the run, queued. It starts within seconds, and anything that needs code, a shell or files gets a fresh sandbox of its own.

    More in Runs and transcripts.

    POST/v1/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"
      }
    }
  3. Read the result

    Poll the run until state is finished, failed or stopped. A finished run carries its result, turns, model calls, tokens and cost; a failed one says why in failure_reason.

    If the agent asked to do something above its level, the run waits for a person in the console. Levels and approvals explains.

    GET/v1/runs/{id}
    curl https://api.rykon.ai/v1/runs/0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40 \
      -H "Authorization: Bearer $RYKON_AI_KEY"
    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"
      }
    }

The reference

58 routes in 11 groups, also as OpenAPI 3.1.