Developer documentation.

Quickstart

The base URL is https://mybuba.com. These public discovery endpoints need no account, API key, or session cookie:

curl https://mybuba.com/api/agent/info
curl https://mybuba.com/api/agent/companions
curl https://mybuba.com/api/agent/companions/luna
curl https://mybuba.com/api/agent/pricing

The responses contain public product information and fictional character profiles. A character slug comes from the public catalogue; an unknown slug does not identify a private or custom companion.

Catalogue filters are optional: query accepts up to 200 characters, style is realistic or anime, category is an ID from the returned category list, and limit is an integer from 1 to 50, defaulting to 20.

curl 'https://mybuba.com/api/agent/companions?style=anime&limit=5'

Catalogue responses include total, hasMore, and nextCursor. To retrieve another page, send the returned nextCursor as the cursor query parameter, retaining the same filters. Stop when hasMore is false and nextCursor is null. Cursors identify the last returned public slug; a cursor that no longer exists in the filtered catalogue returns HTTP 400, so restart pagination if the catalogue changes.

Invalid filters return HTTP 400; unknown public slugs return HTTP 404. The OpenAPI contract describes the HTTP interface.

Start with the product reference, the plain-text index, or agent usage guidance when deciding whether Buba fits a request.

Versions, limits, and errors

The public HTTP API uses major version 1. Send the optional Buba-API-Version: 1 header to pin this major; omitting it selects the current supported major, 1. Responses from /api/agent/* and /ask include Buba-API-Version: 1. Unsupported version values return HTTP 400. Clients should tolerate additive response fields within v1; incompatible changes require a new major and a documented migration.

No retirement of v1 is currently scheduled. Before retiring a supported major, Buba will publish a migration guide and retirement notice in this documentation. When a retirement schedule is announced, affected-version responses will include Deprecation and Sunset headers identifying that schedule. Current v1 responses are not deprecated and have no announced sunset date.

curl https://mybuba.com/api/agent/info \
  -H 'Buba-API-Version: 1'

Public machine endpoints use a best-effort throttle of 120 requests per client per minute in each Worker isolate. Counters use an in-memory client digest and expire with the one-minute window; they are not a globally coordinated quota, billing allowance, or persistent account identifier. No persistent API key is required or issued.

RateLimit-Limit reports the limit, RateLimit-Remaining reports this isolate’s remaining requests, and RateLimit-Reset reports seconds until the current window resets. If HTTP 429 is returned, wait for the number of seconds in Retry-After before retrying. Other infrastructure protections can also affect availability.

HTTP errors use a typed JSON envelope with a stable error.code, a readable error.message, and an error.documentation link:

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "limit must be an integer from 1 to 50.",
    "documentation": "https://mybuba.com/docs"
  }
}

Handle HTTP 400 for invalid arguments or an unsupported API version, 404 for a missing public resource, 405 for an unsupported method, and 429 for throttling. NLWeb query failures also include _meta.response_type: "failure" and version 0.55; unsupported mode and format errors have distinct codes. MCP uses its separate JSON-RPC error and tool-result formats.

These interfaces retrieve public information in the current request. They do not create asynchronous jobs or change account data, so no job-polling flow or idempotency key is needed.

MCP server and tools

Connect a compatible MCP client to https://mybuba.com/mcp using Streamable HTTP. The server is stateless and read-only, and its public tools require no authentication. It does not provide account access or AI chat execution. See the MCP server card for connection metadata.

The product server is listed in the official MCP Registry as com.mybuba/public-discovery. The registry record contains its version and the public https://mybuba.com/mcp connection URL.

For a focused documentation connection, use https://mybuba.com/mcp/docs instead. This optional server exposes only search_docs(query, limit), get_reference(url), and the public reference resource. Read a URL returned by search_docs with get_reference; arbitrary URLs and private account sources are not supported. This documentation server does not expose the companion App or account actions. See its server card.

• get_site_info — Read the current product description, feature availability, and public reference links.
• list_companions — Discover fictional adult characters in the public catalogue.
• get_companion — Read a public character profile by its slug, such as luna.
• search_docs — Search published Buba information and return relevant public sources.
• get_pricing — Read current availability and the status of paid plans and checkout.

Initialize the MCP connection using your client, then use tools/list to read the current input schemas before calling a tool. For example, a JSON-RPC tool-list request is:

curl https://mybuba.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A public profile lookup uses get_companion with its public slug:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_companion",
    "arguments": { "slug": "luna" }
  }
}

list_companions accepts the catalogue filters above. search_docs requires a nonempty query of up to 2,000 characters and an optional integer limit from 1 to 20, defaulting to 5. get_site_info and get_pricing accept an empty arguments object. Unsupported tool arguments return a tool result marked isError: true.

Search public knowledge

/ask searches published Buba information. It returns relevant public sources; it does not generate a companion reply, search private chats, or reveal account data. The MCP search_docs tool offers the same kind of public reference lookup.

For a quick lookup, use GET /ask?query=pricing. For NLWeb v0.55 list-mode requests, send JSON containing query.text and optional response preferences:

curl https://mybuba.com/ask \
  -H 'Content-Type: application/json' \
  --data '{"query":{"text":"Is paid checkout available?"},"prefer":{"mode":"list","response_format":"conversational_search","streaming":false,"limit":5}}'

The query must contain 1 to 2,000 characters. prefer.limit accepts an integer from 1 to 20. The default response is JSON; prefer.streaming: true requests a stream of source results as server-sent events. Only list mode and the conversational_search response format are supported.

Search results are source material. Keep the distinction between current functionality and planned features when explaining them. See current product facts and availability and pricing.

Authentication and private account features

Public discovery, MCP, and public knowledge search do not require authentication. There is no agent API-key sign-up, agent OAuth authorization, or delegated account-access flow.

Private application features use the normal Buba sign-in interface. Firebase handles Google or verified-email sign-in; the application server verifies the identity and creates a secure, HttpOnly session cookie. Private requests remain subject to account ownership, application-origin checks, and service limits.

Do not ask users to paste passwords, identity tokens, or session cookies into an agent conversation. The public tools cannot read saved conversations, favorites, generated images, or custom account companions, and cannot send messages or change an account.

Read the authentication reference and privacy notice.

Current capabilities and boundaries

Buba is for adults 18+. Every current public companion is fictional and AI-generated. Live AI text chat and saved account history require sign-in and connected services; local previews are labeled scripted examples.

Human matching, mystery mode, voice, and video are not available. Live image generation is not currently configured. Paid subscriptions and checkout are not available. The public integration does not enable any of those features.

For product questions, use the official Buba reference. For a creative conversation, let the user choose a companion and continue through the Buba interface.