Cotal Intake API

Open writes: feedback, waitlist, updates, discovery calls.

GitHub OpenAPI

Operations 5

POST /v1/feedback Submit feedback (humans via the site widget, agents via direct POST) #
POST /v1/lead Request a discovery call with the founders #
POST /v1/newsletter Subscribe an email for project updates (capture-only) #
POST /v1/waitlist Join the Cotal Cloud (hosted mesh) waitlist #
POST /v1/telemetry CLI usage telemetry (the cotal CLI posts here) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/cotal-ai:cotal-ai-intake-api"
All apis
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.

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.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cotal-ai-intake-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: cotal.ai public Intake 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: intake
  description: 'Open writes: feedback, waitlist, updates, discovery calls.'
paths:
  /v1/feedback:
    post:
      tags:
      - intake
      operationId: submitFeedback
      summary: Submit feedback (humans via the site widget, agents via direct POST)
      description: 'Open intake. An optional `Authorization: Bearer ctk_…` team key is recorded as a hash for attribution and marks the submission as trusted when recognized. Supports `Idempotency-Key` and `X-Sandbox`.'
      security:
      - {}
      - bearerKey: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/Sandbox'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackInput'
      responses:
        '200':
          description: Stored (or replayed for a known Idempotency-Key). Returns the record id.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitOk'
        '400':
          description: 'Malformed body or validation error (`code`: bad_request | validation_error).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'Body over the size cap (`code`: payload_too_large).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited (`code`: rate_limited). Retry after `Retry-After` seconds.'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Transient storage failure (`code`: storage_error). Safe to retry with the same Idempotency-Key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        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'
  /v1/lead:
    post:
      tags:
      - intake
      operationId: submitLead
      summary: Request a discovery call with the founders
      description: Open intake. A hidden `website` honeypot field is silently dropped server-side. Supports `Idempotency-Key` and `X-Sandbox`.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/Sandbox'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadInput'
      responses:
        '200':
          description: Stored (or replayed for a known Idempotency-Key). Returns the record id.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitOk'
        '400':
          description: 'Malformed body or validation error (`code`: bad_request | validation_error).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'Body over the size cap (`code`: payload_too_large).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited (`code`: rate_limited). Retry after `Retry-After` seconds.'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Transient storage failure (`code`: storage_error). Safe to retry with the same Idempotency-Key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        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'
  /v1/newsletter:
    post:
      tags:
      - intake
      operationId: subscribeNewsletter
      summary: Subscribe an email for project updates (capture-only)
      description: 'Open intake, idempotent per email: a duplicate returns ok with a null id. Supports `X-Sandbox`; `Idempotency-Key` is accepted and ignored because the email already is the key.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/Sandbox'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsletterInput'
      responses:
        '200':
          description: Stored. Returns the new record id (null on duplicate, honeypot, or sandbox).
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitOk'
        '400':
          description: 'Malformed body or validation error (`code`: bad_request | validation_error).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'Body over the size cap (`code`: payload_too_large).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited (`code`: rate_limited). Retry after `Retry-After` seconds.'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Transient storage failure (`code`: storage_error). Safe to retry with the same Idempotency-Key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        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'
  /v1/waitlist:
    post:
      tags:
      - intake
      operationId: joinWaitlist
      summary: Join the Cotal Cloud (hosted mesh) waitlist
      description: 'Open intake, idempotent per email: repeat POSTs upsert the optional fields (one row per email). Supports `X-Sandbox`; `Idempotency-Key` is accepted and ignored because the email already is the key.'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/Sandbox'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaitlistInput'
      responses:
        '200':
          description: On the list (idempotent).
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ok'
        '400':
          description: 'Malformed body or validation error (`code`: bad_request | validation_error).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'Body over the size cap (`code`: payload_too_large).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited (`code`: rate_limited). Retry after `Retry-After` seconds.'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Transient storage failure (`code`: storage_error). Safe to retry with the same Idempotency-Key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        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'
  /v1/telemetry:
    post:
      tags:
      - intake
      operationId: submitTelemetry
      summary: CLI usage telemetry (the cotal CLI posts here)
      description: 'Anonymous usage events from the open-source `cotal` CLI, one per command and one per install per day. The body contract is https://docs.cotal.ai/telemetry: fields are allowlisted by name and type and anything else is dropped. Nothing is stored on cotal.ai; accepted events are relayed to product analytics. Supports `X-Sandbox`. Rate limit: 300 per IP per minute.'
      parameters:
      - $ref: '#/components/parameters/Sandbox'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryInput'
      responses:
        '202':
          description: 'Accepted and relayed (or validated only, with `sandbox: true`).'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ok'
        '400':
          description: 'Malformed body or validation error (`code`: bad_request | validation_error).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'Body over the size cap (`code`: payload_too_large).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited (`code`: rate_limited). Retry after `Retry-After` seconds.'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'Transient storage failure (`code`: storage_error). Safe to retry with the same Idempotency-Key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        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'
components:
  schemas:
    FeedbackInput:
      type: object
      required:
      - summary
      - email
      properties:
        origin:
          type: string
          enum:
          - human
          - agent
          default: human
        type:
          type: string
          enum:
          - bug
          - idea
          - friction
          - praise
          - other
          default: other
        summary:
          type: string
          maxLength: 2000
          description: Required, non-empty.
        email:
          type: string
          format: email
          description: Required — feedback must have a traceable origin.
        severity:
          type: string
          enum:
          - low
          - medium
          - high
        name:
          type: string
          maxLength: 100
        details:
          type: string
          maxLength: 10000
        area:
          type: string
          maxLength: 200
        repro:
          type: string
          maxLength: 10000
        expected:
          type: string
          maxLength: 10000
        actual:
          type: string
          maxLength: 10000
        source:
          type: string
          maxLength: 500
          description: Where it came from, e.g. a page path, agent name, or CLI.
    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.
    TelemetryInput:
      type: object
      required:
      - v
      - installId
      - level
      - event
      - version
      - os
      - arch
      - node
      - ci
      description: One CLI telemetry event. The full field list per event (`command`, `install`) is the contract at https://docs.cotal.ai/telemetry; unknown fields are dropped.
      properties:
        v:
          type: integer
          const: 1
        installId:
          type: string
          format: uuid
          description: Random id of the CLI's settings file, not a person or machine.
        level:
          type: string
          enum:
          - minimal
          - regular
        event:
          type: string
          enum:
          - command
          - install
        version:
          type: string
          description: The cotal-ai version.
        os:
          type: string
        arch:
          type: string
        node:
          type: integer
          description: Node major version.
        ci:
          type: boolean
      additionalProperties: true
    WaitlistInput:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          maxLength: 320
          description: Required. One row per email (upsert).
        linkedin:
          type: string
          maxLength: 500
          description: Optional profile URL.
        useCase:
          type: string
          maxLength: 2000
          description: 'Optional: what they want the hosted mesh for.'
        source:
          type: string
          maxLength: 500
          description: Page path the form was submitted from.
    SubmitOk:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
          const: true
        id:
          type:
          - string
          - 'null'
          format: uuid
          description: Record id; null when nothing was stored (duplicate, honeypot, or sandbox).
        replayed:
          type: boolean
          description: True when a known Idempotency-Key returned the original record.
        sandbox:
          type: boolean
          description: Present and true on X-Sandbox dry runs.
    Ok:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
          const: true
        sandbox:
          type: boolean
          description: Present and true on X-Sandbox dry runs.
    NewsletterInput:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          maxLength: 320
          description: Required.
        source:
          type: string
          maxLength: 500
          description: Page path / placement the form was submitted from.
    LeadInput:
      type: object
      required:
      - email
      - company
      properties:
        email:
          type: string
          format: email
          maxLength: 320
          description: Required, valid work email.
        company:
          type: string
          maxLength: 200
          description: Required.
        role:
          type: string
          maxLength: 120
        agents:
          type: string
          enum:
          - exploring
          - '1'
          - 2-5
          - 6-20
          - 20+
          description: How many agents they run in production.
        frameworks:
          type: array
          items:
            type: string
            maxLength: 60
          maxItems: 20
        coordinating:
          type: string
          maxLength: 2000
        pain:
          type: string
          maxLength: 4000
        source:
          type: string
          maxLength: 500
          description: Page path the form was submitted from.
  headers:
    RateLimit-Policy:
      description: The policy in effect, e.g. `5;w=600` (5 requests per 600 seconds) on writes, `300;w=60` on reads.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    RateLimit-Limit:
      description: Requests allowed per window for this client (per-IP policy).
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the window resets.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
  parameters:
    Sandbox:
      name: X-Sandbox
      in: header
      required: false
      description: 'Set to `true` for a dry run: the request is validated and rate-limited but nothing is stored; the response carries `sandbox: true`.'
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Opaque client-chosen key (1-200 printable ASCII chars; a UUID v4 is ideal). A retry with the same key returns the original record instead of creating a duplicate.
      schema:
        type: string
        minLength: 1
        maxLength: 200
      example: 3f0c6d3a-4b1e-4c9a-9e0b-2c9a1f7d8e21
  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