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

# API Overview

> Introduction to the Qoder Cloud Agents API, gateway URL, request limits, and required headers.

The Qoder Cloud Agents API provides full management capabilities for cloud-hosted AI Agents, covering Agent creation, environment configuration, session management, event streaming, and more. All endpoints follow REST conventions and use JSON for requests and responses.

<Note>The API is currently in Beta. Some functionality may change in future releases.</Note>

## Gateway URL

| Environment | URL                                  |
| ----------- | ------------------------------------ |
| Production  | `https://api.qoder.com/api/v1/cloud` |

## Versioning

The API is currently at version `v1`. All endpoints are versioned through the `v1` segment in the URL prefix `/api/v1/cloud` — no additional version header is required.

## Available APIs

| Resource                 | Description                                                           | Base path                                                    |
| ------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
| Agents                   | Agent CRUD and archival                                               | `/agents`                                                    |
| Environments             | Runtime environment configuration                                     | `/environments`                                              |
| Sessions                 | Agent session creation and lifecycle                                  | `/sessions`                                                  |
| Events                   | Session event stream reads and pushes                                 | `/events`                                                    |
| Files                    | File upload and association                                           | `/files`                                                     |
| Vaults                   | Secure storage for sensitive credentials                              | `/vaults`                                                    |
| Skills                   | Agent skill registration and management                               | `/skills`                                                    |
| Memory Stores            | Persistent memory storage                                             | `/memory_stores`                                             |
| Deployments              | Scheduled deployment automation                                       | `/deployments`                                               |
| Work                     | Self-hosted Environment work queue and worker lease lifecycle         | `/environments/{environment_id}/work`                        |
| Forward Templates        | Forward agent template definition, versioning, archiving, and cloning | `/api/v1/forward/templates`                                  |
| Forward Identities       | Forward identity creation, enable/disable, deletion, and agent lookup | `/api/v1/forward/identities`                                 |
| Forward Identity Configs | Per-identity template config and effective config lookup              | `/api/v1/forward/identities/{identity_id}/templates`         |
| Forward Channels         | Forward channel and QR session management                             | `/api/v1/forward/channels`, `/api/v1/forward/qr_sessions`    |
| Forward Sessions         | Forward session lifecycle, events, and SSE streams                    | `/api/v1/forward/sessions`                                   |
| Forward Resources        | Forward external resource registration and listing                    | `/api/v1/forward/resources`                                  |
| Forward Schedules        | Forward scheduled tasks and run record management                     | `/api/v1/forward/schedules`, `/api/v1/forward/schedule_runs` |

## Request size limits

* Maximum request body size: **4 MB**
* Requests exceeding this limit are truncated, causing JSON parsing to fail with `400 invalid_request_error` (message: "Request body must be valid JSON.").

## Required headers

Every API request must include the authentication header; Content-Type is recommended but not mandatory — the server can auto-detect:

```text theme={null}
Authorization: Bearer $QODER_PAT
Content-Type: application/json  # recommended but not mandatory, server can auto-detect
```

## Beta status

1. The API surface is broadly stable, but signatures may receive minor adjustments in future iterations.
2. New functionality ships behind new beta identifiers.
3. Lock the API version and add compatibility handling when running in production.
4. All current features are available without an additional Beta header.

## Quick connectivity check

```bash theme={null}
# List Agents under the current account (verifies auth and connectivity)
curl -s https://api.qoder.com/api/v1/cloud/agents?limit=1 \
  -H "Authorization: Bearer $QODER_PAT"
```

Successful response:

```json theme={null}
{
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## Rate Limiting

The API application layer currently has no active rate limiting. The gateway layer has global burst traffic suppression and DDoS protection, which may return 429 or 503 when triggered. Clients should implement exponential backoff retry for 5xx/429 (1s → 2s → 4s, max 3 retries).

## Next steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/cloud-agents/api/conventions/authentication">
    Obtain and use a PAT.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/cloud-agents/api/conventions/errors">
    Error codes and troubleshooting.
  </Card>

  <Card title="Pagination" icon="list" href="/cloud-agents/api/conventions/pagination">
    Pagination for list endpoints.
  </Card>
</CardGroup>