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 Session API
version: '1'
license:
name: Apache-2.0
description: 'Operations tagged Session across 2 of this provider''s published API definitions: cotal-ai-manager-console-openapi.json, cotal-ai-manager-console-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://{host}:{port}
variables:
host:
default: 127.0.0.1
port:
default: '12345'
description: Example only. Replace with the port announced by the running service or its owner-private discovery record.
description: Use the manager console address announced by the running manager.
security:
- ConsoleBearer: []
- ConsoleQuery: []
tags:
- name: Session
paths:
/session/{name}:
post:
operationId: establish-console-session
summary: Establish a console mesh session
description: Mint a holder-bound mesh session offer and per-session caller credential for a managed agent. No request body is parsed. The agent name is percent-decoded. Token authorization precedes method and name checks. An open mesh or a manager without a session establisher returns 503 before name validation. Treat the returned creds as secret.
parameters:
- name: name
in: path
required: true
description: Percent-encoded managed agent name.
schema:
type: string
minLength: 1
responses:
'200':
description: Session grant and broker caller connection material.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionEstablishment'
'400':
description: Missing agent name or malformed percent encoding.
content:
text/plain:
schema:
type: string
'401':
description: The manager console token is missing or invalid.
content:
text/plain:
schema:
type: string
'405':
description: Only POST is accepted.
content:
text/plain:
schema:
type: string
headers:
Allow:
schema:
const: POST
'429':
description: Session capacity is exhausted; code is resource-exhausted.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Session establishment failed; native refusals include code.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Session establishment is not available on this manager.
content:
text/plain:
schema:
type: string
tags:
- Session
servers:
- url: http://{host}:{port}
variables:
host:
default: 127.0.0.1
port:
default: '12345'
description: Example only. Replace with the port announced by the running service or its owner-private discovery record.
description: Use the manager console address announced by the running manager.
components:
schemas:
SessionEstablishment:
type: object
properties:
grant:
type: object
description: Native holder-bound session offer from the manager session plane, defined by SPEC section 13.6. The offer alone is not a bearer credential.
wsUrl:
type: string
description: Broker WebSocket URL used for the mesh session.
creds:
type: string
description: Per-session rails-only caller credential.
required:
- grant
- wsUrl
- creds
additionalProperties: false
Error:
type: object
properties:
error:
type: string
code:
type: string
outcome:
type: string
enum:
- not-executed
- executed
- unknown
details: {}
required:
- error
securitySchemes:
ConsoleBearer:
type: http
scheme: bearer
description: Per-manager console token.
ConsoleQuery:
type: apiKey
in: query
name: t
description: Per-manager console token. Takes precedence over Authorization when present.
x-refined-from:
- cotal-ai-manager-console-openapi.json
- cotal-ai-manager-console-openapi.yml
x-source: implementations/auth/src/service.ts ROUTES and loopback handlers