The Activity API from Cotal — 1 operation(s) for activity.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/cotal-ai:cotal-ai-activity-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Cotal Ai Activity API
version: '1'
license:
name: Apache-2.0
description: 'Operations tagged Activity across 2 of this provider''s published API definitions: cotal-ai-dashboard-openapi.json, cotal-ai-dashboard-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://{host}:{port}
description: Your dashboard listener. Broker TLS does not encrypt this HTTP connection.
variables:
host:
default: 127.0.0.1
port:
default: '7799'
security:
- DashboardSession: []
- LaunchToken: []
tags:
- name: Activity
paths:
/api/activity:
get:
operationId: read-activity
summary: Read recent activity
description: Merge the newest chat messages selected by stream sequence with recent direct messages, order by message timestamp and retain the newest limit. partial, missing and reasons identify sources that failed or exceeded the shared 8000 ms deadline. A partial page is still HTTP 200. Failure to obtain the channel list is HTTP 500.
parameters:
- name: limit
in: query
required: false
allowEmptyValue: true
description: Maximum requested messages. Absent or empty uses 200. Accepts decimal digits naming a safe integer, including 0; negative, fractional, whitespace-padded and unsafe values are refused.
schema:
type: integer
minimum: 0
maximum: 9007199254740991
default: 200
example: 20
responses:
'200':
description: The current snapshot or history page.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityPage'
'302':
$ref: '#/components/responses/LaunchExchange'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/CrossOrigin'
'413':
$ref: '#/components/responses/BodyRefused'
'500':
$ref: '#/components/responses/InternalError'
tags:
- Activity
servers:
- url: http://{host}:{port}
description: Your dashboard listener. Broker TLS does not encrypt this HTTP connection.
variables:
host:
default: 127.0.0.1
port:
default: '7799'
components:
responses:
Unauthenticated:
description: No valid session, an invalid launch token, or a spent launch token. The readiness credential does not authorize these routes.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
example:
error: unauthenticated
LaunchExchange:
description: 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:
schema:
type: string
description: The requested path without the query string.
Set-Cookie:
schema:
type: string
description: cotal_web_session=<session>; Path=/; HttpOnly; SameSite=Strict. The default local listener uses HTTP.
InternalError:
description: The request failed. The body names the failure; a failed read does not terminate the dashboard.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
CrossOrigin:
description: Origin is checked before session authentication. An origin outside this listener's allowed origins is refused.
content:
application/json:
schema:
$ref: '#/components/schemas/OriginError'
example:
error: cross-origin
BadRequest:
description: The query or percent-encoded channel name is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BodyRefused:
description: These read routes accept no request body. An announced body is refused before it is read; the connection is closed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
WireExtensionPartKind:
description: Reverse-DNS extension part kind, e.g. `com.acme.snapshot`.
pattern: ^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$
type: string
OriginError:
type: object
properties:
error:
type: string
const: cross-origin
required:
- error
WireJsonValue:
anyOf:
- type: 'null'
- type: boolean
- type: number
- type: string
- items:
$ref: '#/components/schemas/WireJsonValue'
type: array
- additionalProperties:
anyOf:
- $ref: '#/components/schemas/WireJsonValue'
- not: {}
type: object
description: 'Any JSON value (SPEC §5): `null`, a boolean, a number, a string, an array, or an object whose members are JSON values. `undefined` is not a JSON value — `JSON.stringify` omits the key carrying it — so it is excluded at the top level, where it would drop the whole `data` key; an optional member is allowed because serialization drops just that key.'
ActivityPage:
type: object
properties:
entries:
type: array
items:
$ref: '#/components/schemas/ActivityEntry'
partial:
type: boolean
read:
type: integer
minimum: 0
maximum: 2
of:
type: integer
const: 2
missing:
type: array
items:
type: string
enum:
- chat
- direct messages
reasons:
type: object
additionalProperties:
type: string
deadlineMs:
type: integer
const: 8000
required:
- entries
- partial
- read
- of
- missing
- reasons
- deadlineMs
AuthenticationError:
type: object
properties:
error:
type: string
enum:
- unauthenticated
- launch-token-already-used
required:
- error
Error:
type: object
properties:
error:
type: string
required:
- error
WirePart:
oneOf:
- properties:
kind:
const: text
type: string
text:
type: string
required:
- kind
- text
type: object
- properties:
data:
$ref: '#/components/schemas/WireJsonValue'
kind:
const: data
type: string
required:
- kind
- data
type: object
- description: '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`.'
properties:
digest:
description: '`sha256:<hex>` over the raw bytes — the artifact''s identity. The only self-verifying field.'
type: string
pattern: ^sha256:[0-9a-f]{64}$
kind:
const: artifact
type: string
mediaType:
description: MIME type. A publisher's claim.
type: string
name:
description: Human name, e.g. `coverage-report.html`. A publisher's claim, not a checked fact.
type: string
size:
description: 'Size in bytes. A publisher''s claim: a receiver must never preallocate from it.'
type: integer
minimum: 0
required:
- kind
- name
- mediaType
- digest
- size
type: object
- additionalProperties: {}
properties:
kind:
$ref: '#/components/schemas/WireExtensionPartKind'
required:
- kind
type: object
Message:
$ref: '#/components/schemas/WireCotalMessage'
WireEndpointRef:
properties:
id:
type: string
name:
type: string
role:
type: string
required:
- id
- name
type: object
ActivityEntry:
oneOf:
- type: object
properties:
mode:
const: chat
type: string
channel:
type: string
msg:
$ref: '#/components/schemas/Message'
required:
- mode
- channel
- msg
- type: object
properties:
mode:
const: unicast
type: string
msg:
$ref: '#/components/schemas/Message'
required:
- mode
- msg
WireCotalMessage:
description: A message on the mesh (chat / direct message for now; extensible to other families).
oneOf:
- properties:
channel:
description: Channel name — multicast (broadcast to everyone on the channel).
type: string
contextId:
description: Conversation / thread correlation id.
type: string
from:
$ref: '#/components/schemas/WireEndpointRef'
id:
description: Unique message id.
type: string
mentions:
description: 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.
items:
type: string
type: array
parts:
items:
$ref: '#/components/schemas/WirePart'
type: array
replyTo:
description: Id of the message being replied to.
type: string
space:
type: string
ts:
description: Epoch ms.
type: number
required:
- channel
- from
- id
- parts
- space
- ts
type: object
not:
anyOf:
- required:
- to
- required:
- toService
- properties:
contextId:
description: Conversation / thread correlation id.
type: string
from:
$ref: '#/components/schemas/WireEndpointRef'
id:
description: Unique message id.
type: string
mentions:
description: 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.
items:
type: string
type: array
parts:
items:
$ref: '#/components/schemas/WirePart'
type: array
replyTo:
description: Id of the message being replied to.
type: string
space:
type: string
to:
description: Instance id — unicast (direct to one specific endpoint).
type: string
ts:
description: Epoch ms.
type: number
required:
- from
- id
- parts
- space
- to
- ts
type: object
not:
anyOf:
- required:
- channel
- required:
- toService
- properties:
contextId:
description: Conversation / thread correlation id.
type: string
from:
$ref: '#/components/schemas/WireEndpointRef'
id:
description: Unique message id.
type: string
mentions:
description: 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.
items:
type: string
type: array
parts:
items:
$ref: '#/components/schemas/WirePart'
type: array
replyTo:
description: Id of the message being replied to.
type: string
space:
type: string
toService:
description: Service / role — anycast (any one instance of the service receives it).
type: string
ts:
description: Epoch ms.
type: number
required:
- from
- id
- parts
- space
- toService
- ts
type: object
not:
anyOf:
- required:
- channel
- required:
- to
securitySchemes:
DashboardSession:
type: apiKey
in: cookie
name: cotal_web_session
description: Process-local dashboard session issued by the one-use launch URL.
LaunchToken:
type: apiKey
in: query
name: k
description: One-use bootstrap token from the owner-private launch URL. It returns HTTP 302 with a session cookie rather than the requested data.
ReadinessNonce:
type: apiKey
in: header
name: x-cotal-readiness
description: Private startup readiness nonce, accepted only by /api/meta. It does not create a browser session.
externalDocs:
description: Dashboard setup and access limits
url: https://docs.cotal.ai/watch-a-mesh/#web-dashboard
x-refined-from:
- cotal-ai-dashboard-openapi.json
- cotal-ai-dashboard-openapi.yml
x-source: implementations/auth/src/service.ts ROUTES and loopback handlers