Agent HTTP API

A deployed agent is an HTTP service at https://<name>.cycls.ai. This page lists its endpoints. For the Cycls Cloud control plane, see the API reference tab. Authentication: routes marked authenticated require Authorization: Bearer <token>, where the token comes from the configured identity provider. Without Web().auth(...), the state routers are not installed and only the public routes exist. Workspace selection: in multi-workspace mode, send X-Workspace: <id> to act inside a team workspace. No header means the personal one.

Chat

Method	Path	Body	Purpose
`POST`	`/`	`{"messages": [...]}`	the Cycls streaming protocol over SSE
`POST`	`/chat`	same	alias of `/`
`POST`	`/chat/completions`	OpenAI shape	OpenAI-compatible streaming
`POST`	`/chats/{chat_id}/stop`	optional `{"take_back": "<sha256>"}`	stop a running turn
`POST`	`/transcribe`	multipart `file`	voice input to text

curl -N https://my-agent.cycls.ai/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Add ?id=<chat_id> to continue an existing chat. Without it, a new chat id is generated.

from openai import OpenAI

client = OpenAI(base_url="https://my-agent.cycls.ai", api_key="unused")
stream = client.chat.completions.create(
    model="my-agent",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)

/chat/completions sends each event as delta.content unchanged: text arrives as a string and a component as its dict. It ignores detach and sends no chat id. Use POST / when you want the run protocol below. /transcribe takes m4a, mp4, webm, ogg, mp3 or wav, transcribes it with the model .voice() names and returns {"text": ...} alone. A recording the service could not transcribe is a 502. It answers 501 when voice input is off: .voice(False), or no .voice() and no OPENAI_API_KEY.

Run options

Besides messages, the body of POST / takes:

Field	Meaning
`detach`	`true` keeps the run going when the stream closes. Without it, closing the stream stops the run
`regenerate`	the sha256 hex of the text typed in the last user turn. Runs that saved turn again, with its files and @-mentioned connectors, and deletes only what came after it. Answers 409 `{"error": "chat_changed"}` when the last turn is not that one
`retry`	the same hash. Replays the saved turn only if its run did not finish, otherwise sends normally
`disabled_tools`	tools to leave out of this turn, such as `["WebSearch"]`
`approvals`	approval keys from an approval card, for this turn only
`declined`	keys turned down with Not now on an approval card, saved with the turn
`auto`	`false` is the Manual setting under Settings, General, Approvals, so write tools ask first
`connectors`	connectors the person @-mentioned

The stream

The first SSE frame is {"type": "chat_id", "chat_id": "..."}. Components follow, then data: [DONE]. An unhandled error ends the stream with an error callout that carries error_id, the reference to find in the logs. A chat runs one turn at a time. A request while one is running gets 409 {"error": "run_in_progress"} with Retry-After: 2.

Following a run

A detached run outlives its stream. Poll GET /chats/{id}?since=<n>, which returns the turns after n and the state of the run:

Field	Meaning
`run`	`running`, `done`, `failed`, `stopped` or `interrupted`
`next`	the cursor to send as `since` on the next poll
`run_reason`	for `failed` or `interrupted`: `error`, `budget`, `disconnected`, `shutdown`, or `lost` when its heartbeat stopped
`run_error`	the `error_id` of a failed run
`reset`	`true` when the whole chat came back instead of the tail

POST /chats/{id}/stop cancels the run on whichever instance holds it and answers 202 {"stopping": true}. Send {"take_back": "<sha256>"}, the hash of the prompt being stopped, and the run deletes that turn as it ends if it kept nothing after it. The reply then adds taken_back. A run that already finished answers {"stopping": false}, and a chat with no run answers 404.

Configuration and metadata

Method	Path	Purpose
`GET`	`/config`	title, branding, auth flag, feature switches
`GET`	`/og.png`	generated social preview image
`GET`	`/favicon.svg`	favicon
`GET`	`/robots.txt`, `/sitemap.xml`	crawler files
`GET`	`/llms.txt`	a machine-readable summary of the agent
`GET`	`/manifest.webmanifest`	points Chrome’s install sheet at your Play Store app, served when `Web().mobile_app(android=)` is a Play link
`GET`	`/explore`	the agents dropdown list
`GET`	`/examples`	the resolved example gallery, installed only with auth
`GET`	`/public/{path}`	static files from `copy_public`

Chats (authenticated)

Method	Path	Purpose
`GET`	`/chats`	list chats with titles, timestamps, cost and run state
`GET`	`/chats/{id}`	one chat with its messages and run state, `?since=` for the tail
`PUT`	`/chats/{id}`	create or update
`DELETE`	`/chats/{id}`	move to trash, where its id is `chat:{id}`
`DELETE`	`/chats/{id}/last-exchange`	remove the last user turn and everything after it. `?expect=<sha256>` removes it only if it is that turn and its run did not finish

Files (authenticated)

Method	Path	Purpose
`GET`	`/files`	list a folder, with the options below
`GET`	`/files/{path}`	download, `?download` sets an attachment header. A folder downloads as a zip
`PUT`	`/files/{path}`	upload, the raw body is the file, multipart is also accepted. `?dedupe` writes to the next free name, returned as `path`
`POST`	`/files/{path}`	create a directory
`POST`	`/files-batch/{path}`	upload a zip, unpacked under `path`
`PATCH`	`/files/{path}`	rename, body `{"to": "new/path"}`
`DELETE`	`/files/{path}`	delete, which moves to trash

Query	Effect on `GET /files`
`path`	the folder to list, default the workspace root
`sort`, `desc`	order by `name`, `size`, `modified` or `type`, folders first
`search`	up to 12 files under `path` whose path contains every word
`recursive`	everything under `path` as one flat list, up to 2,000 entries
`fresh`	with `search` or `recursive`, wait for a new scan instead of the cached one

Rendering variants for office files: ?as=slides returns per-slide images and ?as=pdf returns a converted PDF. Both require the office render service to be configured. See Files and the canvas.

Trash (authenticated)

Method	Path	Purpose
`GET`	`/trash`	list deleted items
`POST`	`/trash/{id}/restore`	restore one
`DELETE`	`/trash/{id}`	delete one permanently
`DELETE`	`/trash`	empty the trash

Method	Path	Auth	Purpose
`POST`	`/share`	yes	create a share link for a chat or a file
`GET`	`/share`	yes	list share links
`DELETE`	`/share/{token}`	yes	revoke
`GET`	`/shared/{user}/{token}`	no	the public page
`GET`	`/share/{user}/{token}/data`	no	the shared chat or file as JSON
`GET`	`/share/{user}/{token}/file/{path}`	no	a file referenced by the share
`POST`	`/share/{user}/{token}/fork`	yes	copy it into the caller’s workspace

POST /share takes {"path": "chat/<id>"} or {"path": "file/<path>"}, and an optional audience: "public", the default, or "org:<id>", which only signed-in members of that organization can open.

Workspaces (authenticated)

Installed only when Web().workspaces() is enabled.

Method	Path	Purpose
`GET`	`/workspaces`	personal plus teams. `?all=1` for the admin view
`POST`	`/workspaces`	create a team workspace
`PATCH`	`/workspaces/{id}`	rename or set the icon
`DELETE`	`/workspaces/{id}`	delete
`GET`	`/workspaces/{id}/members`	list members
`PUT`	`/workspaces/{id}/members/{user_id}`	add or change a role
`DELETE`	`/workspaces/{id}/members/{user_id}`	remove, or leave

Connectors (authenticated)

Installed when connectors are declared.

Method	Path	Purpose
`GET`	`/connectors`	the directory, with connection state
`POST`	`/connectors/{name}/authorize`	begin an OAuth grant
`GET`	`/connectors/{name}/callback`	OAuth redirect target
`PUT`	`/connectors/{name}/key`	store a pasted key or endpoint
`DELETE`	`/connectors/{name}`	disconnect
`PATCH`	`/connectors/{name}`	`{"on": bool}` switches it for this user. `{"allowed": bool}` is an org admin’s switch for everyone
`GET`	`/connectors/{name}/tools`	tools this connector offers
`PUT`	`/connectors/{name}/tools`	replace every tool setting at once, body `{"tools": {"<tool>": "allow"}}`. `_relay` set to `never` closes `fetch` to apps
`PUT`	`/connectors/{name}/tools/{tool}`	set allow, ask or never for one tool
`GET`	`/connectors/{name}/prompts`	prompts the server publishes
`ANY`	`/connectors/{name}/fetch/{path}`	call the connector’s REST API with the stored credential

Tool settings (authenticated)

Method	Path	Purpose
`GET`	`/tools`	per-user tool switches
`PUT`	`/tools/{tool}`	set allow, ask or never, body `{"mode": "ask"}`
`DELETE`	`/tools/{tool}`	reset to the default

Skills (authenticated)

The routes behind the Skills tab. See Skills. A scope is me, workspace or org, and GET /skills lists the ones the caller may publish to.

Method	Path	Purpose
`GET`	`/skills`	every skill the person’s chats may load, with their switches
`GET`	`/skills/{name}`	one skill, its versions and its files. `?v=` picks a version
`GET`	`/skills/{name}/file?path=`	one file as text. `?v=` picks a version
`PATCH`	`/skills/{name}`	`{"on": bool}` is the person’s switch. `{"allowed": bool}` is an org admin’s, for everyone
`POST`	`/skills?scope=`	a `.skill` or `.zip` as the body: a new skill, or its next version
`PUT`	`/skills/{name}`	write its `SKILL.md` from `{"description", "body", "scope", "title_ar", "description_ar"}` as the next version
`POST`	`/skills/{name}/move`	`{"to": "<scope>"}`: keep it in another scope instead
`POST`	`/skills/{name}/current`	`{"v": n}`: make version `n` the one that loads
`DELETE`	`/skills/{name}`	take it out of every catalog. Its versions are kept
`GET`	`/skills/{name}/download`	the skill as a `.zip`. Not for skills shipped in the image

Memory (authenticated)

The person’s entries in the database tool for the active workspace. Settings lists them as Memory. Turning Memory off is PUT /tools/database with {"mode": "never"}.

Method	Path	Purpose
`GET`	`/memory`	list entries as `[{"key": ..., "value": ...}]`, up to 500
`PUT`	`/memory/{key}`	write one entry, body `{"value": ...}`
`DELETE`	`/memory/{key}`	delete one entry

App data (authenticated)

Used by apps the agent builds. See the Apps tool in Tools.

Method	Path	Purpose
`GET`	`/apps/{slug}/data`	list rows as `{"rows": [...], "truncated": bool}`. `?prefix=` narrows, `?limit=` caps
`GET`	`/apps/{slug}/data/{key}`	read one row as `{"value": ..., "version": ...}`
`PUT`	`/apps/{slug}/data/{key}`	write one row, the body is its JSON value
`DELETE`	`/apps/{slug}/data/{key}`	delete one row

Rows belong to the workspace and its members share them. ?who=me reaches the caller’s own rows instead, and workspace admins can pass a member’s user id, or all for everyone’s. A write with the ?version= of the last read lands only if the row has not changed since, else 412. An empty ?version= writes only a row that does not exist yet. Without it, the last write wins.

Your own routes

Add routes with .server, which is replayed onto the real router inside the container:

from fastapi import Depends


@my_agent.server.api_route("/webhook", methods=["POST"])
async def webhook(request):
    return {"ok": True}


@my_agent.server.api_route("/profile", methods=["GET"])
async def profile(user=Depends(my_agent.auth)):
    return {"id": user.id}

Storage layout

Sessions and files live under /workspace/<scope>/, where the scope is the user or the active workspace. Path traversal is rejected.

Environment variables

Every variable the SDK and runtime read.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Agent HTTP API

Chat

Run options

The stream

Following a run

Configuration and metadata

Chats (authenticated)

Files (authenticated)

Trash (authenticated)

Workspaces (authenticated)

Connectors (authenticated)

Tool settings (authenticated)

Skills (authenticated)

Memory (authenticated)

App data (authenticated)

Your own routes

Storage layout

Next

Environment variables

​Chat

​Run options

​The stream

​Following a run

​Configuration and metadata

​Chats (authenticated)

​Files (authenticated)

​Trash (authenticated)

​Sharing

​Workspaces (authenticated)

​Connectors (authenticated)

​Tool settings (authenticated)

​Skills (authenticated)

​Memory (authenticated)

​App data (authenticated)

​Your own routes

​Storage layout

​Next

Environment variables

Chat

Run options

The stream

Following a run

Configuration and metadata

Chats (authenticated)

Files (authenticated)

Trash (authenticated)

Sharing

Workspaces (authenticated)

Connectors (authenticated)

Tool settings (authenticated)

Skills (authenticated)

Memory (authenticated)

App data (authenticated)

Your own routes

Storage layout

Next