Chat with agents by API

Use the OpenAI-compatible Chat Completions API when you want an external service, script, or OpenAI SDK client to talk to a Manyfold agent.

The public v1 API exposes one integration surface:

POST /api/v1/chat/completions

It works with hosted agents such as Claude Code, Codex, Gemini CLI, OpenClaw, Hermes, Dify, and Langflow agents through the same request shape.

Before you start

1. Create or choose an agent in Manyfold.
2. Copy the agent id. Agent ids start with agt_.
3. Open Settings -> API tokens.
4. Create an API token with the chat.completions scope.
5. Copy the token when it is shown. It will not be shown again.

Use api.full only for trusted internal clients that need the broader Manyfold API. For chat integrations, prefer chat.completions.

Endpoint and model

For the hosted product, use:

https://api.manyfold.ai/api/v1/chat/completions

If you run a self-hosted deployment, replace the origin with your deployment’s API origin.

The model field is the Manyfold agent id, not a provider model name:

{
    "model": "agt_your_agent_id",
    "messages": [{ "role": "user", "content": "Summarize this repository." }]
}

Non-streaming request

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": "system",
        "content": "You are a concise engineering assistant."
      },
      {
        "role": "user",
        "content": "List the next three actions for this project."
      }
    ]
  }'

The response follows the OpenAI Chat Completions shape:

{
    "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": "..."
    }
}

Save metadata.session_id if you want to continue the same Manyfold session later.

Streaming request

Set stream to true to receive Server-Sent Events:

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." }
    ]
  }'

Each event is emitted as:

data: {"object":"chat.completion.chunk",...}

data: [DONE]

The stream also includes the x-session-id response header. Keep that value if you want to continue the session in a later request.

Continue a session

Pass metadata.session_id to continue an existing Manyfold chat session:

{
    "model": "agt_your_agent_id",
    "metadata": {
        "session_id": "cts_existing_session_id"
    },
    "messages": [
        { "role": "user", "content": "Continue from the last result." }
    ]
}

If you omit metadata.session_id, Manyfold creates a new session for that request.

To resume sessions automatically per end user — without tracking session ids yourself — see Per-user sessions.

Send files

A user message can carry image and file content parts alongside text. Files attach to the latest user message:

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": [
          { "type": "text", "text": "What is in this image?" },
          { "type": "image_url", "image_url": { "url": "https://example.com/diagram.png" } }
        ]
      }
    ]
  }'

• image_url.url may be a public https:// URL (fetched server-side) or a base64 data: URL (data:image/png;base64,...).
• For documents, use a file part: { "type": "file", "file": { "filename": "report.pdf", "file_data": "data:application/pdf;base64,..." } }.
• Up to 10 files per message, 25 MB each. A base64 file also counts toward the request body limit (~32 MB), so prefer a URL for large files.
• Files reach Dify agents as native attachments and coding agents (Claude Code, Codex, …) as files in the agent workspace. For a Dify agent, the connected Dify app must have file upload enabled. Self-hosted deployments must configure chat-upload storage for Dify file attachments.

OpenAI SDK example

Most OpenAI-compatible clients let you override the base URL:

import OpenAI from 'openai'

const client = new OpenAI({
    apiKey: process.env.MF_API_TOKEN,
    baseURL: 'https://api.manyfold.ai/api/v1'
})

const response = await client.chat.completions.create({
    model: 'agt_your_agent_id',
    messages: [
        { role: 'user', content: 'Check the deployment plan for risks.' }
    ]
})

console.log(response.choices[0]?.message?.content)

Supported request fields

The endpoint accepts the common Chat Completions fields:

Field	Notes
model	Required. Must be a Manyfold agent id.
messages	Required. system/developer/user/assistant messages. A user message may include image_url and file content parts — see Send files.
stream	Optional boolean. Use true for SSE chunks.
temperature, top_p, max_tokens	Accepted when they are finite numbers.
metadata.session_id	Optional Manyfold session id to continue.
stream_options.include_usage	Optional. When true, streaming can include a usage chunk if usage is available.

Image and file content parts are supported (see Send files). Tool calls, function calls, and raw provider-specific response formats are not part of the v1 public API.

Permission defaults

Coding-agent turns started through this API run unrestricted by default:

Framework	Default
Claude Code	bypassPermissions
Codex	Full access, with approvals and sandboxing bypassed
Gemini CLI	--approval-mode yolo

These defaults let API-driven agents complete file edits, terminal commands, and workspace automation without interactive approval prompts. The OpenAI-compatible v1 endpoint does not expose per-request permission controls; use the Manyfold chat UI or native chat API when you need to choose a narrower mode for a turn.

Errors

Errors use an OpenAI-style shape:

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

Common fixes:

• Use an nca_ API token, not a browser session token.
• Create the token with chat.completions or api.full scope.
• Confirm model is an agent id that belongs to the token owner.
• To send images or documents, use image_url/file content parts (see Send files).