# 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](https://docs.kosa8.com/guides/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](https://docs.kosa8.com/guides/cloud-mcp/) is simpler.

## Auth and errors, as the document states them

- Security scheme `apiKey`: HTTP bearer, the key from [API keys](https://app.kosa8.com/app#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](https://docs.kosa8.com/guides/cloud-webhooks/) for verifying them.

## llms.txt

`https://api.kosa8.com/llms.txt` follows the [llms.txt](https://llmstxt.org/) 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](https://docs.kosa8.com/llms.txt) covering every guide and command.

---
Source: https://docs.kosa8.com/guides/cloud-openapi/