{"openapi":"3.1.0","info":{"title":"Buba Public API","version":"1.0.0","description":"Read-only public fictional adult companion catalogue and documentation search. No authentication, account data or purchases. Send the optional Buba-API-Version: 1 header to pin major version 1; omitting it selects the current supported major, 1. Unsupported versions return HTTP 400. Additive fields may be introduced 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 and retirement notice in its documentation; affected-version responses will include Deprecation and Sunset headers when a retirement schedule is announced. Current v1 responses are not deprecated."},"externalDocs":{"description":"Versioning and deprecation policy","url":"https://mybuba.com/docs#versions-limits"},"servers":[{"url":"https://mybuba.com"}],"security":[],"paths":{"/api/agent/info":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"get":{"operationId":"getSiteInfo","summary":"Read Buba capabilities and limitations","responses":{"200":{"description":"Public site information","headers":{"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid arguments, cursor, or unsupported Buba-API-Version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The public endpoint or companion slug does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The request method is unsupported; inspect the Allow response header.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Best-effort per-isolate client throttle exceeded. Retry after the indicated seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"maximum":60}},"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/companions":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"get":{"operationId":"listCompanions","summary":"Find fictional adult AI companion profiles","description":"Cursor pagination over the filtered public catalogue. Pass nextCursor back as cursor with the same query, style and category filters; stop when hasMore is false and nextCursor is null. Cursors identify the last returned public slug and are valid only while that slug remains in the same filtered catalogue. An invalid cursor returns HTTP 400.","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":200}},{"name":"style","in":"query","schema":{"type":"string","enum":["realistic","anime"]}},{"name":"category","in":"query","schema":{"type":"string","enum":["indian","latina","athletic","goth","blonde","redhead","east-asian","black","creative","gamer","music","anime"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":80,"description":"The nextCursor returned by the preceding page with the same filters."}}],"responses":{"200":{"description":"A bounded page of matching public profiles, categories and pagination state","headers":{"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanionPage"}}}},"400":{"description":"Invalid arguments, cursor, or unsupported Buba-API-Version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The public endpoint or companion slug does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The request method is unsupported; inspect the Allow response header.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Best-effort per-isolate client throttle exceeded. Retry after the indicated seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"maximum":60}},"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/companions/{slug}":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"get":{"operationId":"getCompanion","summary":"Read one public profile","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"Public fictional companion profile","headers":{"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"type":"object","required":["companion","audience"],"properties":{"companion":{"$ref":"#/components/schemas/PublicCompanion"},"audience":{"type":"string"}}}}}},"400":{"description":"Invalid arguments, cursor, or unsupported Buba-API-Version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The public endpoint or companion slug does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The request method is unsupported; inspect the Allow response header.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Best-effort per-isolate client throttle exceeded. Retry after the indicated seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"maximum":60}},"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/pricing":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"get":{"operationId":"getPricing","summary":"Read preview-plan and checkout availability","responses":{"200":{"description":"Current pricing status; no purchasable plans","headers":{"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"type":"object","required":["status","checkoutAvailable","description","url"],"properties":{"status":{"type":"string","const":"preview"},"checkoutAvailable":{"type":"boolean","const":false},"currency":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}},"400":{"description":"Invalid arguments, cursor, or unsupported Buba-API-Version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The public endpoint or companion slug does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The request method is unsupported; inspect the Allow response header.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Best-effort per-isolate client throttle exceeded. Retry after the indicated seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"maximum":60}},"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ask":{"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"get":{"operationId":"searchDocsGet","summary":"Search published Buba documentation with a query string","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000}},{"name":"streaming","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Published source passages, as JSON or an SSE stream of start, result and complete events.","headers":{"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NLWebSearchResults"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Standard error envelope. NLWeb failures for invalid queries, unsupported mode/format or no matching sources also include _meta.response_type=failure and _meta.version=0.55, as specified by NLWebFailure. API-version errors use only the base envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The public endpoint or companion slug does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The request method is unsupported; inspect the Allow response header.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Best-effort per-isolate client throttle exceeded. Retry after the indicated seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"maximum":60}},"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"searchDocs","summary":"Search published Buba documentation with NLWeb v0.55","description":"Read-only retrieval that completes in this response, as JSON or streamed source events. No asynchronous jobs, idempotency keys, or account changes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["text"]},"prefer":{"type":"object","properties":{"streaming":{"type":"boolean","default":false},"mode":{"type":"string","enum":["list"]},"response_format":{"type":"string","enum":["conversational_search"]},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5}}}},"required":["query"]}}}},"responses":{"200":{"description":"Published source passages, as JSON or an SSE stream of start, result and complete events.","headers":{"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NLWebSearchResults"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Standard error envelope. NLWeb failures for invalid queries, unsupported mode/format or no matching sources also include _meta.response_type=failure and _meta.version=0.55, as specified by NLWebFailure. API-version errors use only the base envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The public endpoint or companion slug does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The request method is unsupported; inspect the Allow response header.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Send Content-Type: application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Best-effort per-isolate client throttle exceeded. Retry after the indicated seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"maximum":60}},"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"ApiVersion":{"name":"Buba-API-Version","in":"header","required":false,"description":"Optional major API version. Current/default: 1. Unsupported values return HTTP 400. Clients should tolerate additive fields within the supported major.","schema":{"type":"string","enum":["1"],"default":"1"}}},"headers":{"ApiVersion":{"description":"Major public API version used for this response.","schema":{"type":"string","enum":["1"]}},"RateLimitLimit":{"description":"Best-effort maximum requests per client per Worker isolate during a fixed one-minute window; not a global quota.","schema":{"type":"integer","const":120}},"RateLimitRemaining":{"description":"Requests remaining in this isolate window.","schema":{"type":"integer","minimum":0,"maximum":120}},"RateLimitReset":{"description":"Seconds until the current isolate window resets.","schema":{"type":"integer","minimum":1,"maximum":60}}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","documentation"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"documentation":{"type":"string","format":"uri"}}}}},"NLWebFailure":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","required":["_meta"],"properties":{"_meta":{"type":"object","required":["response_type","version"],"properties":{"response_type":{"type":"string","const":"failure"},"version":{"type":"string","const":"0.55"}}}}}]},"PublicCompanion":{"type":"object","required":["slug","name","age","bio","personality","tags","style","fictional","url","image"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"age":{"type":"integer","minimum":18},"bio":{"type":"string"},"personality":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"style":{"type":"string","enum":["realistic","anime"]},"category":{"type":"string"},"categoryLabel":{"type":"string"},"fictional":{"type":"boolean","const":true},"url":{"type":"string","format":"uri"},"image":{"type":"string","format":"uri"}}},"CompanionPage":{"type":"object","required":["companions","total","categories","audience","nextCursor","hasMore"],"properties":{"companions":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/PublicCompanion"}},"total":{"type":"integer","minimum":0,"description":"All matches before pagination."},"categories":{"type":"array","items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"audience":{"type":"string"},"nextCursor":{"type":["string","null"],"description":"Last returned slug when another page exists; null at the end."},"hasMore":{"type":"boolean","description":"Whether another page exists after this result."}}},"NLWebSearchResults":{"type":"object","required":["_meta","results"],"properties":{"_meta":{"type":"object","required":["response_type","response_format","version"],"properties":{"response_type":{"type":"string","const":"answer"},"response_format":{"type":"string","const":"conversational_search"},"version":{"type":"string","const":"0.55"}}},"results":{"type":"array","items":{"type":"object","required":["@type","name","url","description","grounding"],"properties":{"@type":{"type":"string","const":"WebPage"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"},"grounding":{"type":"object","required":["source"],"properties":{"source":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}}}}}}},"responses":{"InvalidRequest":{"description":"Invalid arguments, cursor, or unsupported Buba-API-Version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"The public endpoint or companion slug does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"The request method is unsupported; inspect the Allow response header.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Send Content-Type: application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Best-effort per-isolate client throttle exceeded. Retry after the indicated seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"maximum":60}},"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SearchInvalidRequest":{"description":"Standard error envelope. NLWeb failures for invalid queries, unsupported mode/format or no matching sources also include _meta.response_type=failure and _meta.version=0.55, as specified by NLWebFailure. API-version errors use only the base envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SearchResults":{"description":"Published source passages, as JSON or an SSE stream of start, result and complete events.","headers":{"Buba-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NLWebSearchResults"}},"text/event-stream":{"schema":{"type":"string"}}}}}}}