OpenAPI REST API

External REST API built with Hono and automatic OpenAPI documentation

OpenAPI REST API

Buda includes a REST API built with Hono and automatic OpenAPI documentation. Perfect for:

  • External integrations (mobile apps, third-party services)
  • Calling Buda Agents from your own product
  • Webhooks and callbacks
  • Non-TypeScript clients

tRPC vs REST: Use tRPC for your Next.js frontend (type-safe, faster). Use the REST API for external clients.

API Documentation Options

Swagger UI

Interactive API explorer with try-it-out feature

OpenAPI JSON

Raw OpenAPI 3.0 specification for tools & SDKs

API Reference

Integrated API reference in the docs site

1. Swagger UI (/api/v1/doc)

The classic interactive API documentation. Test API calls directly from the browser.

https://buda.im/api/v1/doc

Open Swagger UI

2. OpenAPI JSON (/api/v1/openapi.json)

Raw OpenAPI 3.0 specification. Use this for:

  • Generating SDKs with tools like openapi-generator
  • Importing into Postman, Insomnia, or other API clients
  • CI/CD validation and contract testing
https://buda.im/api/v1/openapi.json

View OpenAPI JSON

3. API Reference (Fumadocs Integration)

Beautiful, searchable API documentation integrated into the docs site.

The API Reference is auto-generated from the OpenAPI schema. Run pnpm openapi:generate to update it.

Authentication

The Buda REST API uses API Key authentication. Pass the key in the request header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://buda.im/api/v1/agent-sessions

Treat API Keys like production secrets: never hardcode them in frontend code, rotate immediately if exposed, and keep test and production keys separate.

API Keys can be created and managed in the dashboard under Settings → API Keys.

Quick Start

Health Check

curl https://buda.im/api/v1/health

Response:

{
  "status": "ok",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "version": "1.0.0"
}

List Agent Sessions

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://buda.im/api/v1/agent-sessions

Create a Drive-Based Claw Agent

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/drive/files \
  -H "Authorization: Bearer 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 an Agent Session

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/chat-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "How do I reset my device?", "mode": "chat" }'

Create an API Claw Embed URL

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/embed-urls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "customer-123",
    "displayName": "Kelly",
    "ttlSeconds": 3600,
    "mode": "chat"
  }'

Use the returned embedUrl as the iframe src:

<iframe
  src="https://buda.im/embed/api-claw/tsk_abc123#token=SHORT_LIVED_TOKEN"
  title="API Claw Agent"
  allow="microphone"
  style="width: 400px; height: 600px; border: 0;"
></iframe>

The URL expires according to ttlSeconds. Create a fresh URL from your backend when it expires. Do not put your main API Key in frontend code.

Mint an Embed Session for a Native Frontend

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/embed-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "wechat-openid-oABC123",
    "displayName": "Kelly",
    "ttlSeconds": 3600,
    "mode": "chat"
  }'

The mini program should use the returned short-lived token with /api/v1/embed/chat-sessions/{sessionId} endpoints instead of receiving your main API Key. The /api/v1/embed/... endpoints are JSON APIs, not iframe pages.

On this page

OpenAPI REST APIAPI Documentation Options1. Swagger UI (/api/v1/doc)2. OpenAPI JSON (/api/v1/openapi.json)3. API Reference (Fumadocs Integration)AuthenticationQuick StartHealth CheckList Agent SessionsCreate a Drive-Based Claw AgentAdd Knowledge to the Agent DriveStart an Agent SessionCreate an API Claw Embed URLMint an Embed Session for a Native FrontendRelated Pages