Read direct-message history

GET

/api/dms

curl --request GET \
  --url 'http://127.0.0.1:7799/api/dms?limit=20' \
  --cookie cotal_web_session=<cotal_web_session>

• Your dashboard listener. Broker TLS does not encrypt this HTTP connection.

Return recent direct messages visible to the dashboard observer. A failed or late read returns HTTP 503 instead of a partial array.

Authorizations

• DashboardSession
• LaunchToken

Parameters

Query Parameters

limit

integer

default: 500 <= 9007199254740991

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.

Example

20

Responses

200

The current snapshot or history page.

Media typeapplication/json

Array

One of:

object

object

channel

required

Channel name — multicast (broadcast to everyone on the channel).

string

contextId

Conversation / thread correlation id.

string

from

required

object

id

required

string

name

required

string

role

string

id

required

Unique message id.

string

mentions

Lowercased peer names called out within a channel message — a wake hint that also, on a live channel, routes a durable copy to each mentioned target authorized to read that channel (SPEC §4/§5). It never carries content outside the target’s read ACL and is not a routing substitute for channel/to; the message still multicasts to the whole channel. Omitted when empty.

Array<string>

parts

required

Array

One of:

object

object

kind

required

string

Allowed value: text

text

required

string

object

object

data

required

Any of:

null

null

boolean

boolean

number

number

string

string

Array

Array<object> recursive

object

object

key

additional properties

Any of:

object

Any of:

null

null

boolean

boolean

number

number

string

string

Array

Array<object> recursive

recursive object

object recursive

unknown

kind

required

string

Allowed value: data

object

Reference to bytes in the space’s artifact store — SPEC §5’s reserved slot, now defined. Bare (not reverse-DNS) because it is Cotal’s own core primitive: extension kinds wrap EXTERNAL vocabularies, core kinds are the standard’s own. The full contract, the guard, and the object-store digest boundary live in artifact.ts.

object

digest

required

sha256:<hex> over the raw bytes — the artifact’s identity. The only self-verifying field.

string

/^sha256:[0-9a-f]{64}$/

kind

required

string

Allowed value: artifact

mediaType

required

MIME type. A publisher’s claim.

string

name

required

Human name, e.g. coverage-report.html. A publisher’s claim, not a checked fact.

string

size

required

Size in bytes. A publisher’s claim: a receiver must never preallocate from it.

integer

object

object

kind

required

Reverse-DNS extension part kind, e.g. com.acme.snapshot.

string

/^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/

key

additional properties

replyTo

Id of the message being replied to.

string

space

required

string

ts

required

Epoch ms.

number

Any of:

unknown

unknown

object

object

contextId

Conversation / thread correlation id.

string

from

required

object

id

required

string

name

required

string

role

string

id

required

Unique message id.

string

mentions

Lowercased peer names called out within a channel message — a wake hint that also, on a live channel, routes a durable copy to each mentioned target authorized to read that channel (SPEC §4/§5). It never carries content outside the target’s read ACL and is not a routing substitute for channel/to; the message still multicasts to the whole channel. Omitted when empty.

Array<string>

parts

required

Array

One of:

object

object

kind

required

string

Allowed value: text

text

required

string

object

object

data

required

Any of:

null

null

boolean

boolean

number

number

string

string

Array

Array<object> recursive

object

object

key

additional properties

Any of:

object

Any of:

null

null

boolean

boolean

number

number

string

string

Array

Array<object> recursive

recursive object

object recursive

unknown

kind

required

string

Allowed value: data

object

Reference to bytes in the space’s artifact store — SPEC §5’s reserved slot, now defined. Bare (not reverse-DNS) because it is Cotal’s own core primitive: extension kinds wrap EXTERNAL vocabularies, core kinds are the standard’s own. The full contract, the guard, and the object-store digest boundary live in artifact.ts.

object

digest

required

sha256:<hex> over the raw bytes — the artifact’s identity. The only self-verifying field.

string

/^sha256:[0-9a-f]{64}$/

kind

required

string

Allowed value: artifact

mediaType

required

MIME type. A publisher’s claim.

string

name

required

Human name, e.g. coverage-report.html. A publisher’s claim, not a checked fact.

string

size

required

Size in bytes. A publisher’s claim: a receiver must never preallocate from it.

integer

object

object

kind

required

Reverse-DNS extension part kind, e.g. com.acme.snapshot.

string

/^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/

key

additional properties

replyTo

Id of the message being replied to.

string

space

required

string

to

required

Instance id — unicast (direct to one specific endpoint).

string

ts

required

Epoch ms.

number

Any of:

unknown

unknown

object

object

contextId

Conversation / thread correlation id.

string

from

required

object

id

required

string

name

required

string

role

string

id

required

Unique message id.

string

mentions

Lowercased peer names called out within a channel message — a wake hint that also, on a live channel, routes a durable copy to each mentioned target authorized to read that channel (SPEC §4/§5). It never carries content outside the target’s read ACL and is not a routing substitute for channel/to; the message still multicasts to the whole channel. Omitted when empty.

Array<string>

parts

required

Array

One of:

object

object

kind

required

string

Allowed value: text

text

required

string

object

object

data

required

Any of:

null

null

boolean

boolean

number

number

string

string

Array

Array<object> recursive

object

object

key

additional properties

Any of:

object

Any of:

null

null

boolean

boolean

number

number

string

string

Array

Array<object> recursive

recursive object

object recursive

unknown

kind

required

string

Allowed value: data

object

Reference to bytes in the space’s artifact store — SPEC §5’s reserved slot, now defined. Bare (not reverse-DNS) because it is Cotal’s own core primitive: extension kinds wrap EXTERNAL vocabularies, core kinds are the standard’s own. The full contract, the guard, and the object-store digest boundary live in artifact.ts.

object

digest

required

sha256:<hex> over the raw bytes — the artifact’s identity. The only self-verifying field.

string

/^sha256:[0-9a-f]{64}$/

kind

required

string

Allowed value: artifact

mediaType

required

MIME type. A publisher’s claim.

string

name

required

Human name, e.g. coverage-report.html. A publisher’s claim, not a checked fact.

string

size

required

Size in bytes. A publisher’s claim: a receiver must never preallocate from it.

integer

object

object

kind

required

Reverse-DNS extension part kind, e.g. com.acme.snapshot.

string

/^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/

key

additional properties

replyTo

Id of the message being replied to.

string

space

required

string

toService

required

Service / role — anycast (any one instance of the service receives it).

string

ts

required

Epoch ms.

number

Any of:

unknown

unknown

Example

[
  {
    "parts": [
      {
        "kind": "text"
      }
    ]
  }
]

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.

Headers

Location

string

The requested path without the query string.

Set-Cookie

string

Cotal_web_session=; Path=/; HttpOnly; SameSite=Strict. The default local listener uses HTTP.

400

The query or percent-encoded channel name is invalid.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

401

No valid session, an invalid launch token, or a spent launch token. The readiness credential does not authorize these routes.

Media typeapplication/json

object

error

required

string

Allowed values: unauthenticated launch-token-already-used

Example

{
  "error": "unauthenticated"
}

403

Origin is checked before session authentication. An origin outside this listener’s allowed origins is refused.

Media typeapplication/json

object

error

required

string

Allowed value: cross-origin

Example

{
  "error": "cross-origin"
}

413

These read routes accept no request body. An announced body is refused before it is read; the connection is closed.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

500

The request failed. The body names the failure; a failed read does not terminate the dashboard.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

503

The history read failed or did not finish within 8000 ms.

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}