Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API 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.
openapi: 3.2.0
info:
title: Cotal Ai Membership API
version: '1'
license:
name: Apache-2.0
description: 'Operations tagged Membership 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: Membership
paths:
/api/membership:
get:
operationId: read-membership
summary: Read channel membership
description: Return broker-sourced live and durable channel membership. asOf is absent when no membership heartbeat has been written. Use this for display, not authorization.
responses:
'200':
description: The current snapshot or history page.
content:
application/json:
schema:
$ref: '#/components/schemas/Membership'
'302':
$ref: '#/components/responses/LaunchExchange'
'401':
$ref: '#/components/responses/Unauthenticated'
'403':
$ref: '#/components/responses/CrossOrigin'
'413':
$ref: '#/components/responses/BodyRefused'
'500':
$ref: '#/components/responses/InternalError'
'503':
$ref: '#/components/responses/MembershipUnavailable'
tags:
- Membership
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
MembershipUnavailable:
description: The membership snapshot could not be read. A missing snapshot is not an empty successful one.
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipError'
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:
Membership:
type: object
properties:
asOf:
type: number
members:
type: array
items:
type: object
properties:
id:
type: string
live:
type: array
items:
type: string
durable:
type: array
items:
type: string
observedAt:
type: number
required:
- id
- live
- durable
- observedAt
required:
- members
OriginError:
type: object
properties:
error:
type: string
const: cross-origin
required:
- error
AuthenticationError:
type: object
properties:
error:
type: string
enum:
- unauthenticated
- launch-token-already-used
required:
- error
Error:
type: object
properties:
error:
type: string
required:
- error
MembershipError:
type: object
properties:
error:
type: string
const: membership-read-failed
reason:
type: string
required:
- error
- reason
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