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

# Cloud API

> The REST API behind the CLI: deploy services, manage volumes, read logs and run SQL. Authenticate with an API key or a bearer token.

`https://api.cycls.ai` is the control plane. The [CLI](/ship/cli) is a client
for it, so anything `cycls` can do, your own tooling can do too.

<Note>
  Two different hostnames. `api.cycls.ai` is this platform API, the one the CLI
  calls to build, deploy and manage things. Your own deployments are served at
  `https://<name>.cycls.ai`, and their endpoints are in the
  [Agent HTTP API](/reference/agent-api).
</Note>

## Authentication

Every endpoint accepts either header.

<CodeGroup>
  ```bash API key theme={null}
  curl https://api.cycls.ai/v1/deployment/list \
    -H "X-API-Key: $CYCLS_API_KEY"
  ```

  ```bash Bearer token theme={null}
  curl https://api.cycls.ai/v1/deployment/list \
    -H "Authorization: Bearer $TOKEN"
  ```
</CodeGroup>

Get an API key from [Cycls Cloud](https://cloud.cycls.com). Requests are scoped
to the account that owns the key, so listings return only your resources.

Every endpoint page has a live playground. Paste your key into the
authorization field, fill the parameters, and send the request against
`https://api.cycls.ai` without leaving the page. Start with
[list deployments](/api-reference/deployments/list-service), which is read only.

## What the API covers

| Area        | Endpoints                                                                             |
| ----------- | ------------------------------------------------------------------------------------- |
| Deployments | check a name, deploy, list, delete                                                    |
| Volumes     | create, list, delete, list objects, delete an object, signed upload and download URLs |
| Logs        | fetch log entries, run SQL over logs and billing                                      |
| Billing     | read the account subscription                                                         |

## Deploying

`POST /v1/deploy` takes a multipart form with the source archive and streams
NDJSON progress events back.

```bash theme={null}
curl -X POST https://api.cycls.ai/v1/deploy \
  -H "X-API-Key: $CYCLS_API_KEY" \
  -F "function_name=hello" \
  -F "source_archive=@source.tar.gz" \
  -F "volumes={\"/workspace\": \"hello-chats\"}"
```

Events arrive in order: `BUILDING`, then `DEPLOYING`, then `DONE` or `ERROR`.

Two fields behave as complete declarations rather than patches:

* `volumes` maps mount paths to volumes. `{}` declares no storage. Unknown
  volumes are created and the stream announces it.
* `schedule` sets the cron. Omitting it or sending an empty value removes any
  existing schedule.

The archive is capped at 100 MiB. Ship large files through a volume instead.

## Moving volume data

Uploads and downloads do not pass through the API. Request a signed URL, then
transfer directly to storage.

```bash theme={null}
curl -X POST https://api.cycls.ai/v1/volume/upload \
  -H "X-API-Key: $CYCLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"volume": "training-data", "object": "models/model.bin"}'
```

The response carries a URL you `PUT` the bytes to. `cycls volume put` and
`cycls volume get` do exactly this, which is why file size is effectively
unlimited.

## Rate limits and errors

| Status | Meaning                                                |
| ------ | ------------------------------------------------------ |
| `401`  | missing or invalid credentials                         |
| `403`  | the key does not own the resource                      |
| `404`  | no such deployment or volume                           |
| `422`  | validation error, with the offending field in the body |
| `503`  | a backing service is unavailable, retry                |

## Endpoint reference

Every endpoint, with parameters, schemas and a request builder, is in the pages
under **Endpoints** in the sidebar. The specification is generated from the live
service and mirrored at
[api.cycls.ai/openapi.json](https://api.cycls.ai/openapi.json).