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`	none	stop a running turn
`POST`	`/transcribe`	audio	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,
)

The /chat/completions endpoint flattens components to text, so existing OpenAI clients work unchanged. Use POST / when you want the component stream.

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`	`/explore`	the agents dropdown list
`GET`	`/examples`	the resolved example gallery
`GET`	`/public/{path}`	static files from `copy_public`

Chats (authenticated)

Method	Path	Purpose
`GET`	`/chats`	list chats with titles, timestamps and cost
`GET`	`/chats/{id}`	one chat with its messages
`PUT`	`/chats/{id}`	create or update
`DELETE`	`/chats/{id}`	delete
`DELETE`	`/chats/{id}/last-exchange`	remove the last user and assistant turn

Files (authenticated)

Method	Path	Purpose
`GET`	`/files?path=subdir`	list a directory
`GET`	`/files/{path}`	download, `?download` sets an attachment header
`PUT`	`/files/{path}`	upload, multipart
`POST`	`/files/{path}`	create a directory
`POST`	`/files-batch/{path}`	upload several files
`PATCH`	`/files/{path}`	rename, body `{"to": "new/path"}`
`DELETE`	`/files/{path}`	delete, which moves to trash

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
`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 conversation 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

Workspaces (authenticated)

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

Method	Path	Purpose
`GET`	`/workspace`	the active workspace
`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}`	switch a connector on or off for this user
`GET`	`/connectors/{name}/tools`	tools this connector offers
`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 a switch
`DELETE`	`/tools/{tool}`	reset to the default

App data (authenticated)

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

Method	Path	Purpose
`GET`	`/apps/{slug}/data`	list rows
`GET`	`/apps/{slug}/data/{key}`	read one row
`PUT`	`/apps/{slug}/data/{key}`	write one row
`DELETE`	`/apps/{slug}/data/{key}`	delete one row

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

Configuration and metadata

Chats (authenticated)

Files (authenticated)

Trash (authenticated)

Workspaces (authenticated)

Connectors (authenticated)

Tool settings (authenticated)

App data (authenticated)

Your own routes

Storage layout

Next

Environment variables

​Chat

​Configuration and metadata

​Chats (authenticated)

​Files (authenticated)

​Trash (authenticated)

​Sharing

​Workspaces (authenticated)

​Connectors (authenticated)

​Tool settings (authenticated)

​App data (authenticated)

​Your own routes

​Storage layout

​Next

Environment variables

Chat

Configuration and metadata

Chats (authenticated)

Files (authenticated)

Trash (authenticated)

Sharing

Workspaces (authenticated)

Connectors (authenticated)

Tool settings (authenticated)

App data (authenticated)

Your own routes

Storage layout

Next