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

# APIs

> The REST API behind the console — base URL, bearer authentication, error and pagination conventions, and the interactive reference.

Everything the console does is available under the REST API at `/api/v1`. This page covers the
conventions that hold across every endpoint; for the exact request and response shape of each one,
use the interactive reference served by your own workspace host.

## Base URL

Every endpoint lives under your workspace host. Set it once and the examples throughout these docs
work as written:

```bash theme={null}
export AGENTOPS_URL=https://<your-workspace-host>
```

REST endpoints are then `"$AGENTOPS_URL/api/v1/..."`.

<Info>
  The same host exposes a few sibling surfaces: `/internal/mcp` (the
  [MCP server](/developer-tools/mcp-server)), `/gateway/mcp` (the
  [MCP Gateway](/manage-your-agents/build/mcp-gateway)), `/a2a/...` for agent-to-agent traffic, and
  `/auth/...`.
</Info>

## The interactive reference

The full, always-current reference is served at **`/api/docs`** on your workspace host, and the
**API** link in the top navigation points there. Because it is generated from the running service,
it is authoritative in a way a written page cannot be — you can try requests against your own
workspace from the browser.

## Authentication

Send an [API key](/security-and-governance/identity-and-access/api-keys) as a bearer token on every
request:

```bash theme={null}
curl -H "Authorization: Bearer $AGENTOPS_API_KEY" \
  "$AGENTOPS_URL/api/v1/agents"
```

A key acts either as a
[service account](/security-and-governance/identity-and-access/service-accounts) — preferred for
automation — or as the person who created it. Console requests use the signed session from
single sign-on instead. Either way the request is bound to one identity in one workspace, and what
it may do is governed by that identity's
[roles and grants](/security-and-governance/identity-and-access/roles-permissions).

## Errors

An unauthenticated request gets a JSON `401`. Other failures return a standard status with a JSON
body carrying a readable message:

```json theme={null}
{ "detail": "account agent limit reached (maximum 60); archive or delete an agent before creating a new one" }
```

| Status | Means                                      |
| ------ | ------------------------------------------ |
| `400`  | Invalid request                            |
| `401`  | Missing or invalid credentials             |
| `403`  | Authenticated, but not permitted           |
| `404`  | Not found — or hidden by workspace scoping |
| `409`  | Conflict, such as a quota or a duplicate   |
| `422`  | Validation error                           |

<Note>
  A `404` can mean "exists, but not in your workspace". Resources are scoped to the workspace the
  request resolved to, so a cross-workspace read is a not-found rather than a forbidden — which is
  what keeps one workspace from confirming another's resources exist.
</Note>

## Pagination

List endpoints that can return large result sets accept `limit`, and `offset` where supported. The
exact parameters and any cursor or count fields are documented per endpoint in the interactive
reference.

## Input shapes worth knowing

* **Invoke and schedule** endpoints wrap the run parameters under an `"input"` key.
* **Inbound endpoints are different**: the whole request body is handed to the agent as its input.

## Next steps

<CardGroup cols={2}>
  <Card title="API keys" href="/security-and-governance/identity-and-access/api-keys">
    Issue, reveal, and revoke the tokens these calls use.
  </Card>

  <Card title="MCP server" href="/developer-tools/mcp-server">
    The same capabilities as tools, for a model to call.
  </Card>

  <Card title="Python SDK" href="/developer-tools/python-sdk">
    Building the agents these endpoints invoke.
  </Card>

  <Card title="Limits & quotas" href="/reference/limits-quotas">
    The caps a `409` is telling you about.
  </Card>
</CardGroup>


## Related topics

- [AWS Cost Analyzer](/manage-your-agents/build/catalog/aws-cost-analyzer.md)
- [Build from scratch](/manage-your-agents/build/build-from-scratch.md)
- [MCP server](/developer-tools/mcp-server.md)
- [API keys](/security-and-governance/identity-and-access/api-keys.md)
- [Overview](/developer-tools/overview.md)