> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pomerado.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URL, authentication, conventions and the OpenAPI document of the Pomerado REST API.

The REST API serves programs what the Pomerado MCP serves agents. Each endpoint page in this tab is generated from the same definitions that serve the API, so the reference and the API cannot disagree.

## Base URL and authentication

```text theme={null}
https://api.pomerado.ai/v1
```

Send `Authorization: Bearer <token>` with an [API key](/authentication#use-an-api-key) (`pom_…`) or the Pomerado MCP's [OAuth access token](/rest-api#oauth-access-tokens). Each endpoint page names the callers it accepts, the permission it needs and its effect.

## OpenAPI

The OpenAPI 3.1 document is public:

* `GET https://api.pomerado.ai/v1/openapi.json`, served by the API itself.
* [`/api-reference/openapi.json`](/api-reference/openapi.json) on this site, the copy these pages are built from.

Each operation carries its `operationId` (such as `api_keys.create`) and three extensions: `x-pomerado-effect` (`read`, `write` or `destructive`), `x-pomerado-permission` and, where an API key needs more than its member does, `x-pomerado-key-permission`.

From an MCP client, the same operations are reachable by `operationId` with `search_pomerado_api`, `describe_pomerado_api` and `call_pomerado_api`. See [Pomerado MCP tools](/mcp-reference/pomerado-mcp#pomerado-api-tools).

## Conventions

* JSON keys and enum values are snake\_case; paths are kebab-case.
* IDs are opaque and prefixed by type, such as `key_` for API keys and `int_` for integrations.
* Timestamps are ISO 8601 in UTC and end in `_at`.
* Lists take `?cursor=&limit=` (1 to 100, 20 by default) and answer `{"data": [...], "next_cursor": "…"}`. `next_cursor` is `null` on the last page.
* A create answers `201`, a delete `204` with no body.
* Errors answer `{"error": {"code", "message", "retryable", "docs_url", "details"}}`. Branch on `code`; [errors](/errors) lists every one.
* An operation that would reveal a secret to a program can answer a `dashboard_url` instead, where a signed-in person finishes it.

## Endpoints still moving into this reference

The endpoint pages cover every operation defined in one place for REST, MCP and the Dashboard. These areas still use their own routes and are documented in the guides until they move:

| Area | Guide |
| - | - |
| Finding and running tools: `GET /v1/tools`, `POST /v1/runs` | [Calling tools](/tool-reference) |
| Builds and jobs: `POST /v1/builds`, `GET /v1/jobs/{id}` and its actions | [Jobs and results](/jobs) |
| Saved logins: `/v1/connections` | [Saved logins](/connections) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.