Cotal
DocsAPI Reference

Watch an agent's event frames on a feed

POST
/api/agents/{agent}/watch

Subscribe one open feed to the agent's event-plane frames, which then arrive on that feed as agent-frame events. No body: a watch is a row in this process's map, which the feed's close removes. It changes no mesh state. Watching again is still 204. Other methods fall through to 404.

Authorization

cookiecotal_web_session<token>

Process-local dashboard session issued by the one-use launch URL.

Path Parameters

agent*string

The agent's id, . with each part in [A-Za-z0-9_], percent-encoded as one URL path component. Any other text is refused with 400.

Length3 <= length <= 4096

Query Parameters

feed*string

The id the feed's hello event named. A missing id, or one that is not an open feed of this process, is refused with 400.

Length1 <= length

Response Body

Recorded. No body.

Example Request
curl -X POST 'http://127.0.0.1:7799/api/agents/local.UACCAXW2KQKIQGMNYJFHWTWZSKA3J2TF7EFCABLCXS5UIZATMT345EWS/watch?feed=string'
Example Response
Empty

See the HTTP interface overview for authentication and access requirements.

Complete HTTP contract

Endpoint

POST /api/agents/{agent}/watch

Subscribe one open feed to the agent's event-plane frames, which then arrive on that feed as agent-frame events. No body: a watch is a row in this process's map, which the feed's close removes. It changes no mesh state. Watching again is still 204. Other methods fall through to 404.

Parameters

NameLocationRequiredSchema
agentpathyes{"type":"string","minLength":3,"maxLength":4096}
feedqueryyes{"type":"string","minLength":1}

agent: The agent's id, <owner>.<actor> with each part in [A-Za-z0-9_], percent-encoded as one URL path component. Any other text is refused with 400.

feed: The id the feed's hello event named. A missing id, or one that is not an open feed of this process, is refused with 400.

Responses

HTTP 204

Recorded. No body.

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 agent id or the feed id was refused.

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 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"
}

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.