> ## 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 runs, OpenAI compatibility, chats, files, share links, voice input, workspaces, connectors, skills and tool settings.

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](https://docs.cycls.com/api-reference/introduction.md).

**Authentication:** routes marked authenticated require
`Authorization: Bearer <token>`, where the token comes from the configured
identity provider. Without [`Web().auth(...)`](https://docs.cycls.com/web/auth), the state routers are
not installed and only the public routes exist.

**Workspace selection:** in [multi-workspace mode](https://docs.cycls.com/web/workspaces.md), 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 |

```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=<chat_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,
)
```

`/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()`](https://docs.cycls.com/web/interface#voice-input) 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](https://docs.cycls.com/ship/observability.md#find-one-failed-request).

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](https://docs.cycls.com/agents/files.md).

## 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 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()`](https://docs.cycls.com/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](https://docs.cycls.com/agents/connectors.md) 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](https://docs.cycls.com/agents/knowledge.md#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](https://docs.cycls.com/agents/tools.md#built-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:

```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/<scope>/`, where the scope is the user
or the active workspace. Path traversal is rejected.

## Next

> [card] [Environment variables](https://docs.cycls.com/reference/environment.md)
>
> Every variable the SDK and runtime read.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.