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.

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

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.

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