Developers

REST API

Buda's contract-first REST API at /api/v1 — OpenAPI spec, Swagger UI, and a worked quick start.

Call Buda from any language. The REST API at /api/v1 is contract-first: every endpoint is defined by an oRPC contract, so the OpenAPI spec and Swagger UI are always in sync with what the server actually does. Use it from a backend, a CI job, a non-TypeScript client, or generated SDKs.

Explore the API

Swagger UI

Interactive explorer with try-it-out, right in the browser.

OpenAPI JSON

Raw OpenAPI 3.0 spec for SDK generators and API clients.

buda-cli

Official Rust CLI wrapping every /api/v1 route.

  • Swagger UI (/api/v1/doc) — test calls live with your API key.
  • OpenAPI JSON (/api/v1/openapi.json) — feed it to openapi-generator, Postman, Insomnia, or contract tests.
  • buda-cli (github.com/buda-ai/buda-cli) — the official Rust CLI, no SDK generation needed. There's currently no TypeScript/JS SDK; use the OpenAPI JSON with your generator of choice if you need one.

TypeScript clients can also generate types directly from the exported oRPC contract instead of from the JSON spec.

Authentication

Every protected endpoint expects an sk_ API key as a Bearer token:

curl https://buda.im/api/v1/api-agents \
  -H "Authorization: Bearer sk_your_api_key"

A missing or invalid key returns 401 Unauthorized. See Authentication to create and manage keys.

Quick start

Health check (no auth)

curl https://buda.im/api/v1/health
{ "status": "ok", "timestamp": "2025-01-01T00:00:00.000Z" }

Who am I?

curl https://buda.im/api/v1/users/me \
  -H "Authorization: Bearer sk_your_api_key"

Create a Drive-based Claw agent

curl -X POST https://buda.im/api/v1/api-agents \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "YOUR_SPACE_ID",
    "name": "Watch Assistant",
    "instructions": "Use Drive files as source of truth and keep replies concise."
  }'

Add knowledge to the agent Drive

curl -X PUT https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/drive/files \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "manuals/reset-device.md",
    "content": "# Resetting\n\nHold the crown for 8 seconds.",
    "mimeType": "text/markdown"
  }'

Start a session and poll for the reply

# Send a message — the agent run starts asynchronously (202)
curl -X POST https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/sessions \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "message": "How do I reset my device?", "mode": "chat" }'

# Poll the session until status is completed / waiting_for_input / failed / cancelled
curl https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/sessions/SESSION_ID \
  -H "Authorization: Bearer sk_your_api_key"

Endpoint groups

The API is organized into a few cooperating groups, all under /api/v1:

GroupBase pathWhat it does
System/health, /metaLiveness and service metadata (no auth on /health).
Users/users/meThe authenticated key owner.
API Claws/api-agents, /spaces, /spaces/{id}/agents, .../drive/files, .../sessionsProvision Spaces and hosted agents, manage Drive, run and read sessions, schedule tasks.
Embed.../embed-urls, .../embed-sessions, /embed/chat-sessions/{id}Short-lived iframe URLs and frontend-safe tokens.

For the full request/response shapes, use the live Swagger UI or the OpenAPI JSON.

Authentication

Create and rotate sk_ keys.

API Claws

The full hosted-agent lifecycle.

Embed agents

iframe and native token flows.

Authentication

Create an sk_ API key, authenticate every request, and rotate or expire keys without breaking production.

Model API

Point any OpenAI Responses API client — including OpenAI Codex CLI — at Buda and call any of Buda's models with your existing sk_ API key.

On this page

Explore the APIAuthenticationQuick startHealth check (no auth)Who am I?Create a Drive-based Claw agentAdd knowledge to the agent DriveStart a session and poll for the replyEndpoint groupsRelated