Skip to main content
The /v1 API is authenticated with an API key sent as a bearer token:
Responses are JSON with snake_case fields. A machine-readable OpenAPI 3.1 spec covers every endpoint with operationIds for function calling. Prefer calling agents from an MCP client? See the MCP server.

​
Rate limits

Requests are rate limited per API key. When you exceed the limit the API returns 429 Too Many Requests with a Retry-After header (seconds). Back off and retry.

​
Endpoints

​
Agents & runs

  • GET /v1/agents, POST /v1/agents
  • GET /v1/agents/{id}/versions (the agent’s current graph), POST /v1/agents/{id}/versions
  • GET /v1/agents/{id}/runs
  • GET /v1/runs, GET /v1/runs/{id}
  • GET /v1/tools, POST /v1/tools
Create a built-in tool with POST /v1/tools:
Available keys: wait_until, verify_plan, plan_write, ask_human, knowledge_search, memory_search, memory_write, list_skills, use_skill, calculator. To add one to an agent, GET its versions to read the current graph, push the tool id onto a node’s toolRefs, and POST it back with publish: true.

​
Knowledge

  • GET /v1/knowledge, POST /v1/knowledge, DELETE /v1/knowledge/{kb}
  • GET /v1/knowledge/{kb}/documents, POST /v1/knowledge/{kb}/documents
  • POST /v1/knowledge/search

​
Memory

  • GET /v1/memory, POST /v1/memory, DELETE /v1/memory/{id}
  • POST /v1/memory/search

​
Guardrails & prompts

  • GET /v1/guardrails, POST /v1/guardrails, DELETE /v1/guardrails/{name}
  • GET /v1/prompts, POST /v1/prompts, DELETE /v1/prompts/{name}

​
Evals

  • GET /v1/evals/suites, POST /v1/evals/suites
  • GET /v1/evals/suites/{ref}, PATCH /v1/evals/suites/{ref}, DELETE /v1/evals/suites/{ref}
  • GET /v1/evals/suites/{ref}/cases, POST /v1/evals/suites/{ref}/cases
  • DELETE /v1/evals/cases/{id}
  • GET /v1/evals/experiments, POST /v1/evals/experiments
  • GET /v1/evals/experiments/{id}, PATCH /v1/evals/experiments/{id}, DELETE /v1/evals/experiments/{id}
Suites and agents are addressable by id or name. Suite names are unique per agent rather than per workspace, so a name shared by two agents’ suites returns 409 with the matching ids instead of picking one. GET /v1/evals/experiments/{id} returns the experiment and its leaderboard; add ?results=true for the full case x variant matrix. Aggregates are computed on read, so polling a running experiment returns its partial ranking. DELETE on an experiment cancels it: pending cells are skipped, and cells already mid-run are allowed to finish. See Evals for scorer shapes and worked examples.

​
Run metering

Every run carries a nested usage object. Fields are nullable, and null means unknown - some providers report no usage block, which is not the same as a run that cost nothing. cost_usd is a string because it is an exact decimal.
Eval runs carry source = "eval" and are excluded from GET /v1/runs by default.