Post as the operator
Post one message as the operator the process holds: {kind: "msg", channel, text} to one concrete channel, or {kind: "dm", to, text} to one roster member. The body is read before any refusal, so the 8192-byte cap bounds what a refused post costs, and every check runs before the poster starts, so a refused post never puts the operator on the roster. A wildcard or alias channel, an id not on the roster, an empty text, another kind, or a body that is not a JSON object is refused with 400. A read-only service, an expired operator credential and a cross-origin request answer 403 with the reason. A publish the broker refuses answers 502 with the refusal. Other methods fall through to 404.
cotal_web_session<token>Process-local dashboard session issued by the one-use launch URL.
application/json- body
kind*string"msg""dm"channel?stringThe channel, for kind msg. One concrete channel; no wildcard.
1 <= lengthto?stringThe roster member's agent id, for kind dm.
1 <= lengthtext*stringThe message. Trimmed; an empty text is refused.
1 <= lengthThe post went out.
application/json- response
A post that went out. seq is a DM's stored sequence, the broker's proof that it kept the message; a channel post has none.
ok*truetrueid*stringThe message id.
operatorId*stringThe operator's agent id, the same id /api/meta reports.
seq?integer1 <= valuecurl -X POST 'http://127.0.0.1:7799/api/send' \ -H 'Content-Type: application/json' \ -d '{ "kind": "msg", "channel": "general", "text": "Ship it."}'{ "ok": true, "id": "string", "operatorId": "string", "seq": 1}See the HTTP interface overview for authentication and access requirements.
Complete HTTP contract
Endpoint
POST /api/sendPost one message as the operator the process holds: {kind: "msg", channel, text} to one concrete channel, or {kind: "dm", to, text} to one roster member. The body is read before any refusal, so the 8192-byte cap bounds what a refused post costs, and every check runs before the poster starts, so a refused post never puts the operator on the roster. A wildcard or alias channel, an id not on the roster, an empty text, another kind, or a body that is not a JSON object is refused with 400. A read-only service, an expired operator credential and a cross-origin request answer 403 with the reason. A publish the broker refuses answers 502 with the refusal. Other methods fall through to 404.
Parameters
No operation parameters.
Request body
The request uses the schema below.
Required: yes.
Content type: application/json.
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"msg",
"dm"
]
},
"channel": {
"type": "string",
"minLength": 1,
"description": "The channel, for kind msg. One concrete channel; no wildcard."
},
"to": {
"type": "string",
"minLength": 1,
"description": "The roster member's agent id, for kind dm."
},
"text": {
"type": "string",
"minLength": 1,
"description": "The message. Trimmed; an empty text is refused."
}
},
"required": [
"kind",
"text"
]
}Example: channel
{
"kind": "msg",
"channel": "general",
"text": "Ship it."
}Example: dm
{
"kind": "dm",
"to": "local.UACCAXW2KQKIQGMNYJFHWTWZSKA3J2TF7EFCABLCXS5UIZATMT345EWS",
"text": "How long until the smoke is green?"
}Responses
HTTP 200
The post went out.
Content type: application/json.
{
"$ref": "#/components/schemas/SendAnswer"
}HTTP 302
A valid one-use k query token is exchanged for a dashboard session. The response redirects to the same path without its query. A valid existing cookie takes precedence over k.
Location: The requested path without the query string.
Set-Cookie: cotal_web_session=<session>; Path=/; HttpOnly; SameSite=Strict. The default local listener uses HTTP.
HTTP 400
The target, the text, the kind or the body was refused; the error names which.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 401
No valid session, an invalid launch token, or a spent launch token. The readiness credential does not authorize these routes.
Content type: application/json.
{
"$ref": "#/components/schemas/AuthenticationError"
}Example:
{
"error": "unauthenticated"
}HTTP 403
A browser origin was refused (cross-origin), the service is read-only (post is off in /api/meta), or the operator credential expired.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 413
These read routes accept no request body. An announced body is refused before it is read; the connection is closed.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 500
The request failed. The body names the failure; a failed read does not terminate the dashboard.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 502
The broker refused the publish; the error carries the refusal as it came.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 503
The dashboard is shutting down, so it no longer posts.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}Authentication and access: HTTP interface of the @cotal-ai/web reference implementation. This description covers read operations, readiness metadata and the legacy channel deletion route; it does not establish a separate stable product or Cloud management API. Start the dashboard using the web service preset described in the operator guide. The server defaults to 127.0.0.1:7799; use the host and port configured for your dashboard.
Open the owner-private launch URL once to exchange its k query token for the cotal_web_session cookie. Keep the session on the same host. With the default bind, the permitted browser origins are http://127.0.0.1:<port>, http://localhost:<port> and http://cotal.localhost:<port>. A custom host uses its own HTTP origin. A cross-origin request is refused before session checks. The readiness nonce only opens /api/meta.
Read operations use GET and take no request body. Some read handlers also accept other bodyless methods; this description does not promise a 405 response for them. The native web service is read-only and always refuses channel deletion with 403. Legacy direct dashboard instances can enable deletion; /api/meta reports channelDeleteSupported. Description version 1 identifies this document, not the wire or npm package version.
OpenAPI specification contains the referenced response schemas. Complete Markdown reference.