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 is a client for it, so anything cycls can do, your own tooling can do too.

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.

Authentication

Every endpoint accepts either header.

API key

curl https://api.cycls.ai/v1/deployment/list \
  -H "X-API-Key: $CYCLS_API_KEY"

Get an API key from Cycls Cloud. 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, 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.

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.

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.