Guides / kosa8 Cloud / OpenAPI

OpenAPI and llms.txt

The kosa8 Cloud API describes itself. https://api.kosa8.com/openapi.json is an OpenAPI 3.1 document for code generators and API tools, and https://api.kosa8.com/llms.txt is a short plain-text brief for AI agents.

openapi.json

Every /v1 route the API serves is in it, with its key scope (x-kosa8-scope), parameters, request bodies and error answers. The operator-only /v1/admin routes are left out. A test in the API's own suite fails if a route is added without being described, so the document does not drift from what the server does.

$ curl -s https://api.kosa8.com/openapi.json | jq '.paths | keys'

It is public and needs no key. Use it to:

• Generate a client in a language kosa8 has no SDK for, for example with openapi-generator-cli generate -i https://api.kosa8.com/openapi.json -g rust -o kosa8-rs. The SDKs remain the easier path in Python, JavaScript, Go, Ruby and Java.
• Import into Postman, Insomnia or Bruno: import from URL. Set the bearer token to your k8c_live_… key.
• Give an agent typed tools: frameworks that turn an OpenAPI document into tools (for example LangChain's OpenAPI toolkit) can load it directly. Point them at the Sandboxes tag; for most agents the MCP server is simpler.

Auth and errors, as the document states them

• Security scheme apiKey: HTTP bearer, the key from API keys in the dashboard.
• Every error is {"error": "<code>", "message": "…"}. A 402 (payment_required, spending_cap_reached) also carries upgrade_url and agent_message, the sentence an AI agent should pass to its person.
• Webhook deliveries are described under webhooks; see Webhook recipes for verifying them.

llms.txt

https://api.kosa8.com/llms.txt follows the llms.txt convention: in a page of markdown, how to authenticate, how to connect over MCP, the main calls with their bodies, a curl example, and links to the full reference. Paste its address into an agent's context, or let a crawler find it, and the agent has what it needs to drive the API.

$ curl -s https://api.kosa8.com/llms.txt

The docs site has its own llms.txt covering every guide and command.