> ## 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. # Agent HTTP API > Every endpoint a deployed Cycls agent serves: chat, OpenAI compatibility, chats, files, share links, workspaces, connectors and tool settings. A deployed agent is an HTTP service at `https://.cycls.ai`. This page lists its endpoints. For the Cycls Cloud control plane, see the [API reference tab](/api-reference/introduction). **Authentication:** routes marked authenticated require `Authorization: Bearer `, where the token comes from the configured identity provider. Without [`Web().auth(...)`](/web/auth), the state routers are not installed and only the public routes exist. **Workspace selection:** in [multi-workspace mode](/web/workspaces), send `X-Workspace: ` 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 | ```bash theme={null} curl -N https://my-agent.cycls.ai/ \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"messages": [{"role": "user", "content": "Hello"}]}' ``` Add `?id=` to continue an existing chat. Without it, a new chat id is generated. ```python theme={null} 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](/agents/files). ## 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 | ## Sharing | 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()`](/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](/agents/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](/agents/tools#built-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: ```python theme={null} 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//`, where the scope is the user or the active workspace. Path traversal is rejected. ## Next Every variable the SDK and runtime read.