> ## Documentation index
> Fetch the complete documentation index at: https://docs.manyfold.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Fast reference for integrating Manyfold agents with external apps, scripts, and OpenAI-compatible SDKs.

Source: https://docs.manyfold.ai/api-reference

## Tokens and scopes

Use nca_ API tokens. The chat.completions scope can create chat turns and read the same user-owned API conversations; api.full is for trusted internal clients.

## Endpoints

### POST /api/v1/chat/completions

Create a chat completion. Start a turn with a Manyfold agent through the OpenAI-compatible Chat Completions shape.

Anchor: https://docs.manyfold.ai/api-reference#chat-completions

Auth: Bearer API token with chat.completions or api.full.
Quota: Counts against the monthly API request quota.

| Parameter | Required | Description |
| --- | --- | --- |
| `model` | yes | Manyfold agent id, for example agt_... |
| `messages` | yes | system/developer/user/assistant messages. A user message may include image_url and file content parts. |
| `stream` | no | Set true for Server-Sent Events. |
| `metadata.session_id` | no | Continue an existing Manyfold session returned by a previous turn. |
| `stream_options.include_usage` | no | When true, streaming can include a final usage chunk if usage is available. |

Response:

- Non-streaming responses return chat.completion with choices[0].message.content.
- metadata.session_id and x-session-id identify the Manyfold conversation.
- Streaming responses emit chat.completion.chunk events followed by data: [DONE].

### GET /api/v1/conversations

List conversations. List non-channel conversations created through the OpenAI-compatible v1 API.

Anchor: https://docs.manyfold.ai/api-reference#conversations

Auth: Bearer API token with chat.completions or api.full.
Quota: Read-only endpoint; not counted against monthly API request quota.

| Parameter | Required | Description |
| --- | --- | --- |
| `model` | no | Filter by agent id. Tokens bound to one agent are limited to that agent. |
| `limit` | no | 1-100 results. Defaults to 20. |
| `after` | no | Object id from first_id or last_id for cursor pagination. |
| `order` | no | desc by default. Use asc for oldest first. |

Response:

- Returns an OpenAI-style list envelope with object, data, first_id, last_id, and has_more.
- Each item has id, model, title, created_at, and updated_at.

### GET /api/v1/conversations/{session_id}/messages

List conversation messages. Replay messages for one API-created conversation, including text and full Manyfold content blocks.

Anchor: https://docs.manyfold.ai/api-reference#conversation-messages

Auth: Bearer API token with chat.completions or api.full.
Quota: Read-only endpoint; not counted against monthly API request quota.

| Parameter | Required | Description |
| --- | --- | --- |
| `session_id` | yes | Manyfold session id returned as x-session-id or metadata.session_id. |
| `limit` | no | 1-100 results. Defaults to 20. |
| `after` | no | Object id from first_id or last_id for cursor pagination. |
| `order` | no | desc by default. Use asc for chronological replay. |

Response:

- content is an OpenAI-compatible message parts array.
- content_blocks preserves Manyfold-specific transcript details such as tool calls.