API Reference — Manyfold

Connect in three minutes

Use the hosted API origin, create a scoped token, then send an OpenAI-compatible request where model is your Manyfold agent id.

Base URL: https://api.manyfold.ai/api/v1
Auth: Authorization: Bearer
Recommended scope: chat.completions

Create or choose an agent and copy its agt_ id.
Create an API token in Settings -> API tokens.
Call /chat/completions with Authorization: Bearer $MF_API_TOKEN.

Endpoints

The public v1 surface is intentionally small: create turns, list API-created conversations, and replay messages.

POST /api/v1/chat/completions Start a turn with a Manyfold agent through the OpenAI-compatible Chat Completions shape. GET /api/v1/conversations List non-channel conversations created through the OpenAI-compatible v1 API. GET /api/v1/conversations/{session_id}/messages Replay messages for one API-created conversation, including text and full Manyfold content blocks.

POST /api/v1/chat/completions

Create a chat completion

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

Parameters

Request	Required	Description
model	Required	Manyfold agent id, for example agt_...
messages	Required	system/developer/user/assistant messages. A user message may include image_url and file content parts.
stream	Optional	Set true for Server-Sent Events.
metadata.session_id	Optional	Continue an existing Manyfold session returned by a previous turn.
stream_options.include_usage	Optional	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].

Auth: Bearer API token with chat.completions or api.full.

Quota: Counts against the monthly API request quota.

GET /api/v1/conversations

List conversations

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

Parameters

Request	Required	Description
model	Optional	Filter by agent id. Tokens bound to one agent are limited to that agent.
limit	Optional	1-100 results. Defaults to 20.
after	Optional	Object id from first_id or last_id for cursor pagination.
order	Optional	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.

Auth: Bearer API token with chat.completions or api.full.

Quota: Read-only endpoint; not counted against monthly API request quota.

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

List conversation messages

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

Parameters

Request	Required	Description
session_id	Required	Manyfold session id returned as x-session-id or metadata.session_id.
limit	Optional	1-100 results. Defaults to 20.
after	Optional	Object id from first_id or last_id for cursor pagination.
order	Optional	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.

Auth: Bearer API token with chat.completions or api.full.

Quota: Read-only endpoint; not counted against monthly API request quota.

Examples

Create a non-streaming turn

curl https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "messages": [
      { "role": "user", "content": "Summarize this repository." }
    ]
  }'

Response

{
    "object": "chat.completion",
    "model": "agt_your_agent_id",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "..."
            },
            "finish_reason": "stop"
        }
    ],
    "metadata": {
        "session_id": "cts_...",
        "assistant_message_id": "..."
    }
}

Streaming

Set stream to true to receive Server-Sent Events. The x-session-id response header identifies the Manyfold session.

curl -N https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [
      { "role": "user", "content": "Write a short release note." }
    ]
  }'

List recent conversations

curl "https://api.manyfold.ai/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer $MF_API_TOKEN"

Replay a conversation

curl "https://api.manyfold.ai/api/v1/conversations/cts_your_session_id/messages?order=asc" \
  -H "Authorization: Bearer $MF_API_TOKEN"

Errors

Errors use an OpenAI-style envelope so compatible clients can handle auth and validation failures consistently.

{
    "error": {
        "message": "API token does not have chat.completions scope",
        "type": "authentication_error",
        "code": "invalid_api_key"
    }
}

Full chat guide · Conversation guide