Agent Runtime API reference

Programmatic access to agent runs, steps, checkpoints, and heal history. Agent runtime paths are prefixed with /api/agent-runtime.

Production base URL: https://api.solenai.ca. Self-hosted deployments use your API origin (NEXT_PUBLIC_API_BASE).

Response headers

Every agent-runtime response includes:

X-Solen-Request-Id — correlation ID (CUID or UUID) for support and logs.
X-Solen-Version: 3 — gateway version.

Example response headers

HTTP/1.1 201 Created
X-Solen-Request-Id: clx9k2m00000008l4abc123de
X-Solen-Version: 3
Content-Type: application/json

Authentication

Send your workspace API key on every request using one of:

Header x-api-key: <your-key>
Header Authorization: Bearer <your-key>

Keys are created in the product under Settings → API Keys. The @solenai/sdk sends the key automatically as a Bearer token.

POST /api/agent-runtime/runs — Start a run

Creates a new agent run. Requires a valid workspace API key. The SDK calls this automatically when you invoke withSolen().

Body (JSON)

agentId (string, required) — stable agent identifier
framework (string, required) — langgraph, crewai, autogen, or custom
metadata (object, optional) — custom run metadata

curl — start run

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "agentId": "research-agent",
    "framework": "langgraph",
    "metadata": { "environment": "production" }
  }'

Response (201 Created)

{
  "runId": "clx9k2m00000008l4abc123de",
  "correlationId": "agent-research-agent-1717200000000"
}

POST /api/agent-runtime/runs/:runId/steps — Report a step

Reports a single step within a run. Called by the SDK on every ctx.step() invocation.

curl — report step

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/steps" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "stepNumber": 3,
    "stepType": "tool_call",
    "toolName": "search_web",
    "durationMs": 1240,
    "status": "success"
  }'

POST /api/agent-runtime/runs/:runId/checkpoint — Save state

Persists an encrypted checkpoint of agent state at a given step. Called by ctx.checkpoint() or auto-checkpoint intervals.

curl — checkpoint

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/checkpoint" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "stepNumber": 10,
    "stateJson": "{\"messages\":[...],\"currentStep\":10}",
    "frameworkMeta": { "graphNode": "research" }
  }'

Response (201)

{
  "checkpointId": "chk_abc123",
  "checksum": "sha256:…"
}

PATCH /api/agent-runtime/runs/:runId/status — Complete or fail

Marks a run as completed or failed when your agent finishes.

curl — complete run

curl -sS -X PATCH "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{ "status": "COMPLETED" }'

curl — fail run

curl -sS -X PATCH "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "status": "FAILED",
    "failureDetail": "tool_call_loop: search_web called 23x"
  }'

GET /api/agent-runtime/runs — List runs

Query: limit, status (RUNNING, HEALING, COMPLETED, FAILED), agentId.

curl

curl -sS "https://api.solenai.ca/api/agent-runtime/runs?status=RUNNING&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

GET /api/agent-runtime/runs/:runId — Run detail

Returns one run with steps, checkpoints, heal history, and current status.

curl

curl -sS "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

POST /api/agent-runtime/runs/:runId/rollback — Rollback to checkpoint

Resumes the agent from its last known-good checkpoint after a failed heal attempt.

curl

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/rollback" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

TypeScript SDK — @solenai/sdk

Install from npm and wrap your agent with full types. The SDK handles run creation, step reporting, checkpointing, and status updates automatically.

Install

npm install @solenai/sdk

withSolen()

import { withSolen } from '@solenai/sdk';

const result = await withSolen(
  {
    apiKey: process.env.SOLEN_API_KEY!,
    agentId: 'research-agent',
    framework: 'langgraph',
    baseUrl: 'https://api.solenai.ca',
  },
  async (ctx) => {
    const data = await ctx.step('tool_call', () => searchWeb(query), {
      toolName: 'search_web',
    });
    await ctx.checkpoint({ query, data });
    return data;
  }
);

Context methods: ctx.step(), ctx.checkpoint(). Run fields: runId, correlationId. Config options: checkpointEveryNSteps, maxTokens, debug.

Rate limits

Per-API-key limits (Redis-backed when REDIS_URL is set):

Endpoint	Limit	Notes
POST /api/agent-runtime/runs	100 / min	Per workspace API key
POST …/steps, POST …/checkpoint	1000 / min	High-volume step ingestion
GET /api/agent-runtime/runs	300 / min	Dashboard polling
Other agent-runtime routes	100 / min	Default limit

429 response

{
  "error": "rate_limit_exceeded",
  "retryAfter": 45
}

Retry-After header is set in seconds.

Error codes

HTTP	Meaning
400	Bad request (missing agentId, invalid framework, workspace not resolved).
401	Missing or invalid API key.
403	`insufficient_permissions`
404	Run or checkpoint not found.
429	`rate_limit_exceeded`
500	Server error.

Agent Runtime API reference

Programmatic access to agent runs, steps, checkpoints, and heal history. Agent runtime paths are prefixed with /api/agent-runtime.

Production base URL: https://api.solenai.ca. Self-hosted deployments use your API origin (NEXT_PUBLIC_API_BASE).

Response headers

Every agent-runtime response includes:

X-Solen-Request-Id — correlation ID (CUID or UUID) for support and logs.
X-Solen-Version: 3 — gateway version.

Example response headers

HTTP/1.1 201 Created
X-Solen-Request-Id: clx9k2m00000008l4abc123de
X-Solen-Version: 3
Content-Type: application/json

Authentication

Send your workspace API key on every request using one of:

Header x-api-key: <your-key>
Header Authorization: Bearer <your-key>

Keys are created in the product under Settings → API Keys. The @solenai/sdk sends the key automatically as a Bearer token.

POST /api/agent-runtime/runs — Start a run

Creates a new agent run. Requires a valid workspace API key. The SDK calls this automatically when you invoke withSolen().

Body (JSON)

agentId (string, required) — stable agent identifier
framework (string, required) — langgraph, crewai, autogen, or custom
metadata (object, optional) — custom run metadata

curl — start run

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "agentId": "research-agent",
    "framework": "langgraph",
    "metadata": { "environment": "production" }
  }'

Response (201 Created)

{
  "runId": "clx9k2m00000008l4abc123de",
  "correlationId": "agent-research-agent-1717200000000"
}

POST /api/agent-runtime/runs/:runId/steps — Report a step

Reports a single step within a run. Called by the SDK on every ctx.step() invocation.

curl — report step

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/steps" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "stepNumber": 3,
    "stepType": "tool_call",
    "toolName": "search_web",
    "durationMs": 1240,
    "status": "success"
  }'

POST /api/agent-runtime/runs/:runId/checkpoint — Save state

Persists an encrypted checkpoint of agent state at a given step. Called by ctx.checkpoint() or auto-checkpoint intervals.

curl — checkpoint

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/checkpoint" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "stepNumber": 10,
    "stateJson": "{\"messages\":[...],\"currentStep\":10}",
    "frameworkMeta": { "graphNode": "research" }
  }'

Response (201)

{
  "checkpointId": "chk_abc123",
  "checksum": "sha256:…"
}

PATCH /api/agent-runtime/runs/:runId/status — Complete or fail

Marks a run as completed or failed when your agent finishes.

curl — complete run

curl -sS -X PATCH "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{ "status": "COMPLETED" }'

curl — fail run

curl -sS -X PATCH "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -d '{
    "status": "FAILED",
    "failureDetail": "tool_call_loop: search_web called 23x"
  }'

GET /api/agent-runtime/runs — List runs

Query: limit, status (RUNNING, HEALING, COMPLETED, FAILED), agentId.

curl

curl -sS "https://api.solenai.ca/api/agent-runtime/runs?status=RUNNING&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

GET /api/agent-runtime/runs/:runId — Run detail

Returns one run with steps, checkpoints, heal history, and current status.

curl

curl -sS "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

POST /api/agent-runtime/runs/:runId/rollback — Rollback to checkpoint

Resumes the agent from its last known-good checkpoint after a failed heal attempt.

curl

curl -sS -X POST "https://api.solenai.ca/api/agent-runtime/runs/clx9k2m00000008l4abc123de/rollback" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

TypeScript SDK — @solenai/sdk

Install from npm and wrap your agent with full types. The SDK handles run creation, step reporting, checkpointing, and status updates automatically.

Install

npm install @solenai/sdk

withSolen()

import { withSolen } from '@solenai/sdk';

const result = await withSolen(
  {
    apiKey: process.env.SOLEN_API_KEY!,
    agentId: 'research-agent',
    framework: 'langgraph',
    baseUrl: 'https://api.solenai.ca',
  },
  async (ctx) => {
    const data = await ctx.step('tool_call', () => searchWeb(query), {
      toolName: 'search_web',
    });
    await ctx.checkpoint({ query, data });
    return data;
  }
);

Context methods: ctx.step(), ctx.checkpoint(). Run fields: runId, correlationId. Config options: checkpointEveryNSteps, maxTokens, debug.

Rate limits

Per-API-key limits (Redis-backed when REDIS_URL is set):

Endpoint	Limit	Notes
POST /api/agent-runtime/runs	100 / min	Per workspace API key
POST …/steps, POST …/checkpoint	1000 / min	High-volume step ingestion
GET /api/agent-runtime/runs	300 / min	Dashboard polling
Other agent-runtime routes	100 / min	Default limit

429 response

{
  "error": "rate_limit_exceeded",
  "retryAfter": 45
}

Retry-After header is set in seconds.

Error codes

HTTP	Meaning
400	Bad request (missing agentId, invalid framework, workspace not resolved).
401	Missing or invalid API key.
403	`insufficient_permissions`
404	Run or checkpoint not found.
429	`rate_limit_exceeded`
500	Server error.