Cotal Newsletter API

openapi: 3.2.0
info:
  title: cotal.ai public Newsletter API
  version: 1.1.0
  summary: Open HTTP endpoints on cotal.ai for humans, CLIs and agents.
  description: 'Cotal puts your AI agents in one shared space. Claude Code, Codex, OpenCode, Hermes, Jcode and pi hand off work directly and ask you when a decision needs you. Open source under Apache-2.0. Cotal Cloud, in closed alpha, runs it for you.


    These endpoints are open by design so agents and CLIs can call them directly. Conventions:


    - **Errors** are always JSON (`Error` schema) with a stable `code` and a `hint`, never an HTML page.

    - **Rate limits**: writes 5 per IP per 10 minutes and 30 globally per minute; reads 300 per IP per minute (`/v1/health` exempt). Every response carries the RFC `RateLimit-*` headers; a `429` adds `Retry-After`.

    - **Idempotency**: send `Idempotency-Key` on `POST /v1/feedback` and `POST /v1/lead`; a retry with the same key returns the original record (`replayed: true`). `/v1/waitlist` and `/v1/newsletter` are idempotent per email.

    - **Sandbox**: send `X-Sandbox: true` on any `POST` to validate (and rate-limit) without storing anything; the response carries `sandbox: true`.

    - **Pagination**: list endpoints are cursor-based (`limit`, `cursor` → `next_cursor`).

    - **Versioning and deprecation**: the version is in the path (`/v1`). Within `/v1`, fields are only ever added, never removed or renamed. A breaking change ships under a new prefix (`/v2`) while `/v1` keeps running. When an operation is deprecated it answers with `Deprecation: true` and a `Sunset` header carrying the removal date, at least 90 days ahead, and the change is announced in the API llms.txt and the build log. Nothing is deprecated today.

    - **MCP**: the same actions are exposed as MCP tools at https://cotal.ai/mcp (Streamable HTTP, no credentials); see the server card at https://cotal.ai/.well-known/mcp/server-card.json.

    - **Auth**: how credentials work is written up at https://cotal.ai/auth.md.'
  contact:
    name: Cotal
    email: hello@cotal.ai
    url: https://cotal.ai/contact
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-mcp:
    url: https://cotal.ai/mcp
    transport: streamable-http
    serverCard: https://cotal.ai/.well-known/mcp/server-card.json
  x-deprecation-policy:
    versioning: URL prefix (/v1); additive changes only within a prefix; breaking changes ship under /v2 with /v1 kept running.
    noticePeriodDays: 90
    headers:
    - Deprecation
    - Sunset
    announcedAt:
    - https://cotal.ai/api/llms.txt
    - https://cotal.ai/blog
    currentlyDeprecated: []
servers:
- url: https://cotal.ai
  description: Production. Sandbox mode is the X-Sandbox header, not a separate host.
tags:
- name: Newsletter
paths:
  /v1/newsletter:
    options:
      operationId: newsletterPreflight
      summary: CORS preflight
      responses:
        '204':
          description: No Content
        default:
          description: Any other failure. The body is always the Error object, with a stable `code` and a `hint`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Newsletter
components:
  schemas:
    Error:
      type: object
      description: Every failure, on every endpoint. Never an HTML page.
      required:
      - ok
      - error
      - code
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          enum:
          - bad_request
          - validation_error
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - payload_too_large
          - rate_limited
          - storage_error
          description: Stable, machine-readable error code.
        hint:
          type: string
          description: How to recover.
        docs:
          type: string
          format: uri
          description: Where the contract is documented.
  securitySchemes:
    bearerKey:
      type: http
      scheme: bearer
      bearerFormat: ctk_…
      description: 'Registered Cotal tester/agent key. How to get one: https://cotal.ai/auth.md'
    adminKey:
      type: http
      scheme: bearer
      bearerFormat: cpa_…
      description: 'Admin key of the Cotal team, accepted on /v1/posts only: stage and revise every post. It cannot publish; that is a human click in the private area. Not issued to outside callers.'
externalDocs:
  description: Cotal documentation
  url: https://docs.cotal.ai