Skip to main content
POST
Message a factory's manager agent
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/factories/sendMessage stores your message in one of a factory’s chat sessions and schedules the factory’s manager agent to answer it, as sending a message in the factory’s Console chat does. Each call is a billable model turn. The body is strict: factoryId, sessionId and content (1–32,000 characters). Any other key is 400 bad_request, so a message carries text only: file attachments and knowledge requests are not accepted. The session must be open (ACTIVE or PAUSED) and in one of the factory’s channels; the factory’s channelIds (from Get a factory) name them. Create a session with POST /api/v2/chat/createSession on one of those channels. A session that is not open or not in the factory answers 404 with Session not found. A factory you cannot read (factories:read at its home org unit) answers 404 with Factory not found. You need factories:manage at the factory’s home and at the session’s home (its channel’s org unit); otherwise the answer is 403 and nothing is stored. A factory that is not active (paused, archived or still provisioning) answers 409 invalid_state with The factory is not active, and nothing is stored. The answer is 200 with {id, sessionId, messageId, queued}. messageId is your stored prompt message, not the reply: the manager answers later in the same session, and you read the reply with GET /api/v2/chat/listMessages. When the session’s previous turn is still running, your message waits behind it: queued is true and messageId is null. A Personal key writes the message as its owner; an External App or platform key writes it as itself. Each call stores a message and starts a turn, so send an Idempotency-Key to make a retry safe: the same key and body within 24 hours returns the recorded 200 only while you may still message that factory in that session; otherwise 409 idempotency_result_unavailable, and the message is never stored twice. The credential’s scopes must reach factories:manage: the permission is the fence (see Scopes).

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

factoryId
string
required

The factory whose manager agent receives the message.

Minimum string length: 1

Body

application/json
sessionId
string
required

An open chat session in one of the factory's channels (channelIds on the factory).

Minimum string length: 1
content
string
required
Required string length: 1 - 32000

Response

Message a factory's manager agent

data
object
required
meta
object
required