CotalRead direct-message history
Return recent direct messages visible to the dashboard observer. A failed or late read returns HTTP 503 instead of a partial array.
cotal_web_session<token>Process-local dashboard session issued by the one-use launch URL.
limit?integerMaximum requested messages. Absent or empty uses 500. Accepts decimal digits naming a safe integer, including 0; negative, fractional, whitespace-padded and unsafe values are refused.
0 <= value <= 9007199254740991500The current snapshot or history page.
application/json- response
[index: integer]?||A message on the mesh (chat / direct message for now; extensible to other families).
curl -X GET 'http://127.0.0.1:7799/api/dms?limit=20'[ { "channel": "string", "contextId": "string", "from": { "id": "string", "name": "string", "role": "string" }, "id": "string", "mentions": [ "string" ], "parts": [ { "kind": "text", "text": "string" } ], "replyTo": "string", "space": "string", "ts": 0 }]See the HTTP interface overview for authentication and access requirements.
Complete HTTP contract
Endpoint
GET /api/dmsReturn recent direct messages visible to the dashboard observer. A failed or late read returns HTTP 503 instead of a partial array.
Parameters
| Name | Location | Required | Schema |
|---|---|---|---|
| limit | query | no | {"type":"integer","minimum":0,"maximum":9007199254740991,"default":500} |
limit: Maximum requested messages. Absent or empty uses 500. Accepts decimal digits naming a safe integer, including 0; negative, fractional, whitespace-padded and unsafe values are refused.
Responses
HTTP 200
The current snapshot or history page.
Content type: application/json.
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Message"
}
}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 query or percent-encoded channel name is invalid.
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
Origin is checked before session authentication. An origin outside this listener's allowed origins is refused.
Content type: application/json.
{
"$ref": "#/components/schemas/OriginError"
}Example:
{
"error": "cross-origin"
}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 503
The history read failed or did not finish within 8000 ms.
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.