Cotal Intake API
Open writes: feedback, waitlist, updates, discovery calls.
Open writes: feedback, waitlist, updates, discovery calls.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/cotal-ai:cotal-ai-intake-api"
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.
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: 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