API Claw - Smart Hardware & Third-Party Developer Integration

Smartwatches, IoT devices, chat plugins - they all want built-in AI Agents. But running a large model on-device isn't viable: not enough compute, too much power draw, poor results.

API Claw is built for this. With a few API calls to Buda's OpenAPI, third-party developers can give their products a cloud-based OpenClaw AI Agent with conversation capability and a private knowledge base, waking on demand and consuming zero resources at rest.

In practice, you are not integrating a raw model API. You are integrating a managed Agent capability layer that already includes model access, runtime, knowledge base, session management, and operational scaling.

Who it's for

• Smart hardware makers - watches, earbuds, IoT devices that want a built-in AI assistant
• Software developers - mini-programs, apps, browser extensions that want to embed AI chat
• SaaS providers - who want to offer customers an "AI-powered private space"

Two common buyer types

1. Chat apps, SaaS tools, and third-party software

If you already have a product with users, conversations, forms, or workflows, API Claw lets you add an AI Agent without building the whole backend stack yourself.

Examples:

• A chat app that wants to add an AI assistant into every conversation
• A customer service SaaS that wants each customer to have a private AI support agent
• A browser extension or internal enterprise tool that needs a cloud-based AI worker

2. Hardware manufacturers

If you are building a smartwatch, earbuds, a voice terminal, or another connected device, API Claw lets the device connect to a cloud AI brain instead of trying to run the intelligence locally.

That means:

• The device handles input and output
• The Agent runs in the cloud
• Upgrades happen server-side instead of through constant firmware complexity

How it works

Your product (hardware / software)
        ↓  API call
  Buda OpenAPI
        ↓
  Space (tenant)
        ↓
  Agent (AI assistant) + Drive (knowledge base)
        ↓
  Chat Session (conversation)

Each end user gets an independent Chat Session with isolated context. The Agent sleeps when idle and wakes automatically when a message arrives.

What you do not need to build yourself

With API Claw, the developer does not need to separately build or operate:

• Model configuration and provider switching
• Inference machines or GPU infrastructure
• Agent runtime and tool sandboxing
• File ingestion and knowledge base processing
• Session and context management
• Tenant isolation for different users or customers
• Wake/sleep orchestration for idle agents

This is the key value: your team can focus on the product experience, while Buda provides the Agent infrastructure layer behind it.

Why not just call an LLM API directly?

Calling a model API gives you model output. API Claw gives you an operational AI Agent.

If you are a product company, this difference matters more than model quality alone.

API Claw vs OpenClaw

OpenClaw is the Agent capability and runtime layer. API Claw is the productized API surface that lets external hardware and software connect to that capability.

In simple terms:

• OpenClaw = the underlying Agent runtime / capability model
• API Claw = the developer-facing integration layer built on top of it

API surface at a glance

API Claw is easiest to understand as five cooperating API groups:

API Claw has its own hosted iframe surface. Your backend creates a short-lived embed URL:

POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "externalUserId": "customer-123",
  "displayName": "Kelly",
  "ttlSeconds": 3600,
  "mode": "chat"
}

The response includes:

{
  "embedUrl": "https://buda.im/embed/api-claw/tsk_abc123#token=SHORT_LIVED_TOKEN",
  "sessionId": "tsk_abc123",
  "expiresAt": "2026-05-26T12:00:00.000Z"
}

Then iframe the returned embedUrl:

<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 token lives in the URL hash fragment so it is not sent to the server as part of the initial page request. The page reads the token in the browser and uses it only for /api/v1/embed/... JSON calls. When the token expires, create a fresh embed URL from your backend.

How application scenarios combine the APIs

Most products use the same lifecycle: provision, seed, run, read, learn, and update.

Rule of thumb:

• Put durable knowledge in Drive.
• Put transient user input in a Chat Session.
• Put customer or device isolation in Spaces.
• Put role, behavior, and runtime identity in Agents.
• Use Embed API only when the caller is a frontend that cannot safely hold your main API Key.

Integration steps

POST /api/v1/spaces
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "name": "Acme Device Fleet",
  "slug": "acme-device-fleet"
}

POST /api/v1/spaces/{spaceId}/agents
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "name": "Watch Assistant",
  "emoji": "AI",
  "instructions": "You are a smartwatch assistant. Use Drive files as source of truth. Keep replies short enough for a small screen."
}

PUT /api/v1/spaces/{spaceId}/agents/{agentId}/drive/files
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "path": "manuals/reset-device.md",
  "mimeType": "text/markdown",
  "content": "# Resetting the device\n\nHold the crown for 8 seconds, then confirm on screen."
}

POST /api/v1/spaces/{spaceId}/agents/{agentId}/chat-sessions
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "message": "How do I reset my device?",
  "mode": "chat"
}

GET /api/v1/agent-sessions/{sessionId}
Authorization: Bearer <your-api-key>

OpenAPI endpoints for API Claw

These endpoints are available in the OpenAPI JSON at /api/v1/openapi.json and the interactive Swagger UI at /api/v1/doc.

Which URL should I iframe?

For API Claw, your backend should call this OpenAPI endpoint first:

POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls

It returns an embedUrl like:

https://buda.im/embed/api-claw/{sessionId}#token={shortLivedToken}

That exact returned URL is the iframe src.

Use this when:

• You want a ready-made Buda-hosted API Claw chat UI.
• You need a link that expires on a schedule.
• You are embedding into a website, admin panel, customer portal, or partner console.
• Your product backend can refresh the URL before or after expiration.

Do not iframe /api/v1/embed/.... Those routes are JSON APIs used by the hosted iframe page and by native frontends. For WeChat mini programs, mobile apps, and browser extensions, build your own chat UI and call:

POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-sessions
POST /api/v1/embed/chat-sessions/{sessionId}/messages
GET  /api/v1/embed/chat-sessions/{sessionId}

That gives the frontend a scoped, short-lived token without exposing your main Buda API Key.

Embedded chat for mini programs

For WeChat mini programs, mobile apps, browser extensions, or any frontend you do not fully control, do not ship your main Buda API Key to the client.

Use the embed flow instead:

1. Your backend calls Buda with the real API Key and mints a short-lived embed token.
2. Your mini program stores only that short-lived token.
3. The mini program sends messages and polls status through /api/v1/embed/....
4. When the token expires, your backend mints a fresh one.

Backend: mint an embed session

POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-sessions
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "externalUserId": "wechat-openid-oABC123",
  "displayName": "Kelly",
  "ttlSeconds": 3600,
  "mode": "chat",
  "metadata": {
    "miniProgram": "wechat",
    "scene": "device-support"
  }
}

Return only token, sessionId, and the required API URLs to the mini program. For an iframe, call /embed-urls instead and return embedUrl.

Mini program: send a message

POST /api/v1/embed/chat-sessions/{sessionId}/messages
Authorization: Bearer <embed-token>
Content-Type: application/json

{
  "message": "How do I reset my device?",
  "mode": "chat"
}

Mini program: poll for replies

GET /api/v1/embed/chat-sessions/{sessionId}
Authorization: Bearer <embed-token>

This gives mini programs a clean native integration path without iframe constraints, third-party cookie issues, or leaked server credentials.

Minimal Node.js example

const API_BASE = "https://buda.im/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.BUDA_API_KEY}`,
  "Content-Type": "application/json",
};

const space = await fetch(`${API_BASE}/spaces`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Acme Device Fleet" }),
}).then((res) => res.json());

const agent = await fetch(`${API_BASE}/spaces/${space.id}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Watch Assistant",
    instructions: "Answer from Drive first. Keep replies concise.",
  }),
}).then((res) => res.json());

await fetch(`${API_BASE}/spaces/${space.id}/agents/${agent.id}/drive/files`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
    path: "manuals/reset-device.md",
    content: "# Resetting\n\nHold the crown for 8 seconds.",
    mimeType: "text/markdown",
  }),
});

const started = await fetch(`${API_BASE}/spaces/${space.id}/agents/${agent.id}/chat-sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "How do I reset my device?", mode: "chat" }),
}).then((res) => res.json());

const status = await fetch(`${API_BASE}/agent-sessions/${started.session.id}`, {
  headers: { Authorization: headers.Authorization },
}).then((res) => res.json());

Building a continuously evolving Drive-based Agent

The useful pattern is not "send everything in every prompt." Let your product treat Drive as the Agent's durable brain:

• Write product manuals, policies, release notes, and user-specific state into Drive.
• Start each conversation with a small runtime message, such as the user's question or latest device event.
• Poll the Chat Session for status and messages.
• When your product learns something durable, write it back to Drive as a file.
• Let the next run inherit that improved context automatically.

This is how a device or third-party app gets an Agent that improves over time: the API call wakes the Agent, the session captures the immediate conversation, and Drive carries forward the durable knowledge.

Billing model

Typical model:

• You buy Spaces from Buda (volume pricing available)
• You charge your end users a subscription or activation fee
• The margin is yours

Why hardware teams care

For hardware companies, this changes the cost structure:

• No need to ship a device powerful enough to run a full AI stack locally
• No need to keep a user's laptop or phone acting as the primary runtime
• No need to maintain a separate AI backend team just to support one device line

Your hardware can stay lightweight while the AI capability keeps improving in the cloud.

Analogy: ChatGPT vs OpenAI

The difference: Buda OpenAPI isn't just model inference — it provides a complete Agent runtime including knowledge base, session management, and tool-calling capabilities.

Why not OpenClaw?

OpenClaw is a great open-source AI Agent project, perfect for individuals who want to self-host an assistant on their own machine. But for hardware or software developers who need to scale, it's the wrong tool.

For a full comparison, see: Buda vs OpenClaw

In one line: OpenClaw is a tool for personal use. Buda is infrastructure developers sell to their users.

If you need to give 100,000 smartwatches each their own AI assistant, you need Buda, not a separate OpenClaw instance running behind every device.

FAQ

Do end users need a Buda account? No. End users have no visibility into Buda. Your product proxies all interactions through the API.

Does the Agent consume resources when idle? No. The Agent sleeps when there are no active conversations and wakes automatically when a message arrives.

Can I configure different Agent instructions for different users? Yes. Each Space has its own independent Agent configuration. Create separate Spaces and Agents per user as needed.