CommonTape Keys API
The Keys API from CommonTape — 1 operation(s) for keys.
The Keys API from CommonTape — 1 operation(s) for keys.
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/commontape-com:commontape-com-keys-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: Commontape Com Keys API
version: 1.0.0
x-word-list-version: 6
description: 'Operations tagged Keys across 2 of this provider''s published API definitions: commontape-com-agent-api-openapi.json, commontape-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://commontape.com
tags:
- name: Keys
paths:
/api/v1/keys:
post:
summary: Get your own key (no key needed)
description: 'Register once and get a key, shown ONCE in this answer: keep it and send it as Authorization: Bearer on every other call. Starter limits: 30 requests a minute, 3 open holds, 5 bookings a day. The email sent to contact_email carries a link that raises the key to standard limits (60 a minute, 10 open holds, no daily cap) and your key page (usage, the name owners see, rotate, revoke). Limits on registering: 3 keys a day per contact address, 5 per sending IP. Browsers may post the same fields as a form from /docs. The same operation is the register tool over MCP.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_name
- owner_label
- contact_email
properties:
agent_name:
type: string
minLength: 1
maxLength: 60
example: acme-travel-bot
description: What your agent or product is called.
owner_label:
type: string
minLength: 1
maxLength: 40
example: Acme Assistant
description: 'The plain name business owners see next to a job from this key: letters, digits, spaces and a few marks; no machine words.'
contact_email:
type: string
format: email
description: 'A working address: it gets the link that raises the limits and your key page link. Never the key.'
notify_url:
type: string
format: uri
maxLength: 2000
example: https://agent.example/commontape/notices
description: Optional. An https address of yours that takes a POST. CommonTape sends a push notice there (see webhooks) when one of this key's jobs is declined, called off by the owner, booked on the owner's yes, or runs out unanswered. A public host name only (no IP address, no private host); a refusal says why. Without it, poll status.
responses:
'201':
description: Issued. The key is in this answer once.
content:
application/json:
schema:
type: object
required:
- key
- key_id
- name
- owner_label
- tier
- limits
- standard_limits
- shown_once
- email_sent
- next_actions
properties:
key:
type: string
example: ct_live_...
description: 'Shown once. Send as Authorization: Bearer <key>.'
key_id:
type: string
format: uuid
name:
type: string
description: The key's name (your agent_name, with a short suffix when that name was taken).
owner_label:
type: string
tier:
type: string
enum:
- starter
- standard
- partner
limits:
$ref: '#/components/schemas/KeyLimits'
standard_limits:
$ref: '#/components/schemas/KeyLimits'
shown_once:
type: boolean
enum:
- true
email_sent:
type: boolean
description: 'Whether the email with the limits link went out. If false, ask for a fresh link later: POST /api/v1/keys/link {contact_email}.'
notify_url:
type:
- string
- 'null'
description: The push notice address as registered, or null.
notify_secret:
type:
- string
- 'null'
description: 'Shown once, only with a notify_url: the secret every push notice is signed with (x-commontape-signature = hex HMAC-SHA256 of the exact body). Keep it with the key. Rotating the key makes a new one, shown once on the key page.'
next_actions:
type: array
items:
type: string
enum:
- search
'400':
description: A field is missing or malformed (INVALID_REQUEST). The message names the field; next_actions says fix_request.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- next_actions
properties:
code:
type: string
message:
type: string
next_actions:
type: array
items:
type: string
'429':
description: Too many keys from this address (3 a day) or this connection (5 a day) (RATE_LIMITED). The message says when to try again.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- next_actions
properties:
code:
type: string
message:
type: string
next_actions:
type: array
items:
type: string
default:
$ref: '#/components/responses/Error'
tags:
- Keys
operationId: postApiV1Keys
x-operation-id-source: derived
servers:
- url: https://commontape.com
components:
schemas:
KeyLimits:
type: object
required:
- requests_per_minute
- open_holds
- bookings_per_day
properties:
requests_per_minute:
type: integer
open_holds:
type: integer
bookings_per_day:
type:
- integer
- 'null'
description: null = no daily cap.
responses:
Error:
description: Error
content:
application/json:
schema:
type: object
properties:
error:
type: object
required:
- code
- message
- next_actions
properties:
code:
type: string
enum:
- OUTSIDE_AREA
- OUTSIDE_HOURS
- CAPACITY_FULL
- SERVICE_UNKNOWN
- PRICE_MISMATCH
- HOLD_EXPIRED
- OWNER_DECLINED
- OWNER_UNDID
- SLOT_TAKEN
- REV_STALE
- QUOTE_EXPIRED
- INVALID_STATE
- ALREADY_BOOKED
- ALREADY_CANCELLED
- MODIFICATION_CONFLICT
- PRICE_CHANGED
- HOLD_EXISTS
- BUSINESS_UNAVAILABLE
- NEEDS_OWNER_APPROVAL
- SUPPLIER_CANCELLED
- INSUFFICIENT_NOTICE
- CALENDAR_BUSY
- UNAUTHORIZED
- RATE_LIMITED
- INVALID_REQUEST
- NOT_FOUND
- IDEMPOTENCY_KEY_CONFLICT
- TEMPORARY_ERROR
description: 'Authoritative. The ten business codes (AGT-8); the transaction codes (QUOTE_EXPIRED: quote again; INVALID_STATE: not allowed in this state, read status; ALREADY_BOOKED; ALREADY_CANCELLED; MODIFICATION_CONFLICT: the job changed while you acted, or the quote is not this job''s; PRICE_CHANGED: the price moved since the quote, see price_changed and hold the new quote_token; HOLD_EXISTS: you already hold this job at this business, see transaction_id; NEEDS_OWNER_APPROVAL: a change of a booked job needs the owner''s yes, cancel and book new; SUPPLIER_CANCELLED: the business called off this job, search again with recovery.job; BUSINESS_UNAVAILABLE: the business stopped taking jobs or no longer does this one, see reasons and alternatives; CALENDAR_BUSY: the time is busy in the business''s own calendar feed, read right before the hold, see alternatives for the next free window); and the protocol codes.'
message:
type: string
description: Plain words for a person. The code is what to act on.
next_actions:
type: array
items:
type: string
enum:
- provide_missing_input
- quote
- hold
- book
- await_supplier_approval
- select_alternative_window
- search
- cancel
- status
- wait_for_job
- retry_later
- fix_request
- register
description: The suggested next steps, from a fixed list.
state:
type: string
enum:
- quote_incomplete
- quoted
- held
- pending_approval
- booked
- completed
- declined
- cancelled
- supplier_cancelled
- expired
description: The job's state, when the refusal is about it.
booking_authority:
type: object
description: 'When the refusal is about who may book (modify): the authority the change was judged under.'
required:
- mode
- reasons
- version
properties:
mode:
type: string
enum:
- auto
- approval_required
reasons:
type: array
items:
type: string
examples:
- owner_approves_every_job
- over_auto_book_limit
- business_not_listed
- special_request
- cond.very_dirty
version:
type: integer
description: The owner's booking setting's version (versions.booking_authority).
price_changed:
type: object
required:
- old_amount
- new_amount
- currency
- reasons
description: 'PRICE_CHANGED: the old and new amount and the lines that changed.'
properties:
old_amount:
type: number
new_amount:
type: number
currency:
type: string
reasons:
type: array
items:
type: string
description: The price lines that were added, removed or changed (breakdown keys such as base, bedrooms, cond.pets, minimum_adjustment), or price_rules_changed when the business changed how it prices.
quote_token:
type: string
description: 'PRICE_CHANGED: a token for the same job at the new price. Hold it as it is.'
transaction_id:
type: string
format: uuid
description: 'HOLD_EXISTS: your open hold of this same job at this business.'
retry_after_seconds:
type: integer
minimum: 1
description: 'RATE_LIMITED for holds you let run out: when the next hold is allowed again.'
reasons:
type: array
items:
type: object
properties:
code:
type: string
label:
type: string
description: 'BUSINESS_UNAVAILABLE: why the business can no longer do this job (not_taking_jobs, or a near-miss reason such as a must-have it no longer offers).'
alternatives:
type: array
maxItems: 6
description: 'Ready alternatives for the same job, worked out on every answer by the same judge as search: up to 3 other times at this business and up to 3 other businesses. An alternative never misses a must-have, never offers a must-not and never adds back a task the customer left out; a nice-to-have it misses is named in why. Each is priced for its own window (its day and hour charges): hold its quote_token with its allocation_id as it is.'
items:
type: object
required:
- kind
- slug
- display_name
- service_key
- allocation_id
- window_start
- window_end
- price
- quote_token
- expires_at
- why
properties:
kind:
type: string
enum:
- same_business_other_time
- other_business_same_job
slug:
type: string
display_name:
type: string
service_key:
type: string
allocation_id:
type: string
format: uuid
window_start:
type: string
format: date-time
window_end:
type: string
format: date-time
job_hours:
type:
- integer
- 'null'
minimum: 1
description: 'How long this job takes on site, in whole hours: hourly services the hours asked (rounded up); other services the booking length plus the business''s bigger-homes hours when the home meets its rule. For a business that builds its open times from its working hours (discover capacity.jobs_at_once), every offered time is exactly this long.'
job_people:
type:
- integer
- 'null'
minimum: 1
description: 'How many cleaners this job takes: an hourly price''s people, the business''s usual crew (crew.min), more when the home meets its crew rule (crew.rule), at least 2 for a must-not crew.solo or must-have crew.two_or_more, 3 for crew.three_or_more. Counted against capacity.cleaners. null while the quote is incomplete.'
price:
type: object
properties:
amount:
type: number
currency:
type: string
quote_token:
type: string
expires_at:
type: string
format: date-time
booking_authority:
type:
- object
- 'null'
why:
type: array
items:
type: string
description: 'Fixed codes: other_time, other_business, nice_to_have_missed:<word>, needs_owner_approval.'
alternatives_note:
type: string
enum:
- timed_out
- none_found
description: 'Why alternatives is empty: none fit every must, or they could not be worked out within 4 seconds (the refusal is never delayed for them).'
if_changed:
type: array
maxItems: 2
description: 'Businesses that could do this job if the customer gave up ONE thing (up to 2). None of them can be held or booked from this item: it carries no quote_token and no allocation_id. Ask the customer; if they agree, search again without change.word (that is a new job). A must-have the business said it does not offer, or a must-not that is its only option, is the only kind of change listed; never something the business has not answered, what it takes (the home), a condition of the home, or a second change. You can still quote such a business by name, but do not book it with the job unchanged without the customer''s yes.'
items:
type: object
required:
- slug
- display_name
- service_key
- change
- price_if_changed
- earliest_window_start
- nice_to_have_missed
- needs_owner_approval
- next_step
properties:
slug:
type: string
display_name:
type: string
service_key:
type: string
change:
type: object
description: 'The one thing the customer would give up: a word out of must_have or out of must_not, with the business''s own reason.'
properties:
from:
type: string
enum:
- must_have
- must_not
word:
type: string
code:
type: string
label:
type: string
price_if_changed:
type: object
properties:
amount:
type: number
currency:
type: string
description: 'The changed job''s search price at this business: the same number a search without change.word shows. Not the price at earliest_window_start when the business charges for days or hours.'
earliest_window_start:
type:
- string
- 'null'
format: date-time
nice_to_have_missed:
type: array
items:
type: string
needs_owner_approval:
type: boolean
description: The changed job would wait for the owner's yes there.
next_step:
type: string
enum:
- ask_customer_then_search
if_changed_note:
type: string
enum:
- timed_out
- none_found
description: 'Why if_changed is empty: no business is one change away, or they could not be worked out within the 4 seconds (the ready alternatives are kept).'
change:
type: object
description: 'modify refusals: the change it would have been, with refused (the kind whose check said no). The booked job is unchanged.'
properties:
kinds:
type: array
items:
type: string
enum:
- non_commercial
- commercial
- eligibility
- capacity
- approval
rechecked:
type: array
items:
type: string
enum:
- non_commercial
- commercial
- eligibility
- capacity
- approval
price:
type: object
properties:
from:
type: number
to:
type: number
currency:
type: string
from_version:
type:
- integer
- 'null'
to_version:
type:
- integer
- 'null'
refused:
type: string
enum:
- non_commercial
- commercial
- eligibility
- capacity
- approval
description: 'On a refusal: the kind whose check said no. The booked job is unchanged.'
recovery:
type: object
description: 'SUPPLIER_CANCELLED, and ALREADY_CANCELLED on a job the business called off: the job to search again with.'
properties:
job:
type: object
alternatives:
type: array
maxItems: 6
description: 'Ready alternatives for the same job, worked out on every answer by the same judge as search: up to 3 other times at this business and up to 3 other businesses. An alternative never misses a must-have, never offers a must-not and never adds back a task the customer left out; a nice-to-have it misses is named in why. Each is priced for its own window (its day and hour charges): hold its quote_token with its allocation_id as it is.'
items:
type: object
required:
- kind
- slug
- display_name
- service_key
- allocation_id
- window_start
- window_end
- price
- quote_token
- expires_at
- why
properties:
kind:
type: string
enum:
- same_business_other_time
- other_business_same_job
slug:
type: string
display_name:
type: string
service_key:
type: string
allocation_id:
type: string
format: uuid
window_start:
type: string
format: date-time
window_end:
type: string
format: date-time
job_hours:
type:
- integer
- 'null'
minimum: 1
description: 'How long this job takes on site, in whole hours: hourly services the hours asked (rounded up); other services the booking length plus the business''s bigger-homes hours when the home meets its rule. For a business that builds its open times from its working hours (discover capacity.jobs_at_once), every offered time is exactly this long.'
job_people:
type:
- integer
- 'null'
minimum: 1
description: 'How many cleaners this job takes: an hourly price''s people, the business''s usual crew (crew.min), more when the home meets its crew rule (crew.rule), at least 2 for a must-not crew.solo or must-have crew.two_or_more, 3 for crew.three_or_more. Counted against capacity.cleaners. null while the quote is incomplete.'
price:
type: object
properties:
amount:
type: number
currency:
type: string
quote_token:
type: string
expires_at:
type: string
format: date-time
booking_authority:
type:
- object
- 'null'
why:
type: array
items:
type: string
description: 'Fixed codes: other_time, other_business, nice_to_have_missed:<word>, needs_owner_approval.'
alternatives_note:
type: string
enum:
- timed_out
- none_found
description: 'Why alternatives is empty: none fit every must, or they could not be worked out within 4 seconds (the refusal is never delayed for them).'
next_step:
type: string
enum:
- search_again_with_job
earliest:
type: string
format: date-time
description: 'INSUFFICIENT_NOTICE (M-21): no start before this is taken (RFC 3339, business offset): the later of the notice cutoff and the first calendar day the same-day / next-day No allows. A later time may still be closed (weekends, holidays, working hours): pick from available_windows.'
reason:
type: string
enum:
- scope_not_confirmed
description: 'SERVICE_UNKNOWN on a direct quote (M-21): the owner has not confirmed what this service includes (discover matchable false).'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your agent key (ct_live_...). Get one with POST /api/v1/keys (no key needed); the demo key ct_demo_... needs no registration.
x-refined-from:
- commontape-com-agent-api-openapi.json
- commontape-com-openapi.yml