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/docOpen 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.jsonView 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-sessionsTreat 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/healthResponse:
{
"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