Cotal Channel API

openapi: 3.2.0
info:
  title: Cotal Ai Channel API
  version: '1'
  license:
    name: Apache-2.0
  description: 'Operations tagged Channel 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: Channel
paths:
  /api/channel/delete:
    post:
      operationId: delete-dashboard-channel
      summary: Delete a legacy dashboard channel
      description: Legacy direct dashboard operation. The native lifecycle web service always returns 403 before reading the body because it has no channel-purger authority. Check channelDeleteSupported in /api/meta. A legacy instance deletes one concrete canonical channel and its content using its configured purger authority. Wildcards, aliases and missing channels are refused. The body limit is 8192 bytes. JSON is parsed without a Content-Type check. Other methods fall through to 404.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  minLength: 1
              required:
              - channel
            example:
              channel: general
      responses:
        '200':
          description: Channel content was purged and its configuration removed as reported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelDeleted'
        '302':
          $ref: '#/components/responses/LaunchExchange'
        '400':
          description: Missing or non-canonical channel, malformed JSON, or deletion refusal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          description: A browser origin was refused, or the native service is configured read-only. A read-only refusal includes code PERMISSION_DENIED.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum:
                    - PERMISSION_DENIED
                required:
                - error
        '413':
          $ref: '#/components/responses/BodyRefused'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Channel
    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'
    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:
    AuthenticationError:
      type: object
      properties:
        error:
          type: string
          enum:
          - unauthenticated
          - launch-token-already-used
      required:
      - error
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    ChannelDeleted:
      type: object
      properties:
        ok:
          const: true
        channel:
          type: string
        purged:
          type: integer
          minimum: 0
        removed:
          type: boolean
      required:
      - ok
      - channel
      - purged
      - removed
      additionalProperties: false
  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