{"openapi":"3.1.0","info":{"title":"coss.com API","version":"2026-10-10","description":"One API key for every coss.com product. Errors share one envelope: `Error`. Every request is scoped to the environment the key belongs to; domains and the audit log are organization-wide."},"servers":[{"url":"https://api.coss.com"}],"tags":[{"name":"Environment","description":"The environment, project and organization an API key belongs to."},{"name":"Emails","description":"Send transactional email and follow its delivery."},{"name":"Email templates","description":"Versioned, localized subjects and bodies with typed variables, sent by id or alias."},{"name":"Suppressions","description":"Addresses that sends skip, added by bounces, complaints or you."},{"name":"Sub-accounts","description":"Your users, each with their own domains, suppressions, quotas and reputation (email for platforms)."},{"name":"Tracking","description":"Which emails of the environment have their opens and clicks tracked."},{"name":"SMS","description":"Send text messages from the organization's numbers, follow their delivery, and read replies and opt-outs."},{"name":"Signature requests","description":"Ask people to sign PDFs, in your app or by email, with an audit trail and a sealed copy."},{"name":"Sign documents","description":"PDFs uploaded for signature requests, with their pages and text anchors."},{"name":"Sign templates","description":"Reusable documents with fields for roles, made into requests, edited in the embedded builder."},{"name":"Sign settings","description":"Which sites may embed the signing page, how it looks, and what signers consent to."},{"name":"Verifications","description":"One-time codes by SMS or email, checked against what the end user typed, behind a fraud guard."},{"name":"Forms","description":"Hosted form endpoints your site posts to, screened by Risk and delivered to webhooks, email and contacts."},{"name":"Form submissions","description":"What people submitted to a form, with uploaded files; release spam, or delete."},{"name":"Scheduling hosts","description":"The people who can be booked: your doctors, tutors or consultants."},{"name":"Scheduling schedules","description":"A host's weekly hours and date overrides, in their local time."},{"name":"Scheduling event types","description":"What can be booked: one-on-one, a pool, collective or a group session."},{"name":"Scheduling availability","description":"Which times can be booked, for one event type or across many hosts."},{"name":"Scheduling bookings","description":"Bookings and holds: create, reschedule, cancel, approve and erase."},{"name":"Scheduling series","description":"Recurring bookings, whose occurrences can each move on their own."},{"name":"Scheduling calendars","description":"Connect a host's calendars, and choose which of them count."},{"name":"Scheduling settings","description":"Embedding origins, branding, notifications and calendar failure behaviour."},{"name":"Receiving","description":"Email received at the environment's inbound address and receiving domains."},{"name":"Inboxes","description":"Email addresses for agents: received mail kept as threads, sends and replies from the address."},{"name":"Contacts","description":"The people marketing email goes to, with their properties and consent."},{"name":"Audiences","description":"Lists of contacts that broadcasts are sent to."},{"name":"Segments","description":"Contacts chosen by their properties, always up to date."},{"name":"Topics","description":"What contacts subscribe to, and the environment's marketing settings."},{"name":"Broadcasts","description":"Marketing email sent to an audience or segment."},{"name":"Reputation","description":"The organization's sending standing (good, warning or suspended) and why."},{"name":"Domains","description":"The organization's verified sending domains."},{"name":"Dedicated IPs","description":"The organization's own sending IPs, warmed up automatically (an add-on)."},{"name":"Webhook endpoints","description":"URLs that receive the environment's delivery events, signed."},{"name":"Hooks applications","description":"Hooks (webhooks as a service): your customers, each with their own endpoints and portal."},{"name":"Hooks event types","description":"The catalog of messages you send, which your customers subscribe from."},{"name":"Hooks endpoints","description":"Your customers' URLs that receive their messages, each signed with its own secret."},{"name":"Hooks messages","description":"Send a message once; coss.com delivers it to every subscribed endpoint, with retries."},{"name":"Hooks portal","description":"A ready-made page for your customers to manage their endpoints."},{"name":"Logs","description":"The environment's API requests, email events and webhook attempts."},{"name":"Log drains","description":"Endpoints of yours that receive the environment's logs as signed batches."},{"name":"Audit log","description":"Changes to the organization, by members, API keys and coss.com support."},{"name":"Billing","description":"The organization's plan, usage, invoices and credits."},{"name":"Risk","description":"Assess sign-ups, logins and other events: a decision with reasons, from signals and what the environment remembers."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A secret API key from the dashboard: `coss_live_…` for production environments, `coss_test_…` for sandbox environments."}},"schemas":{"EmailWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id: the same as `EmailEvent.id`, and the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","email.unsubscribed"]},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"bounce":{"type":"object","properties":{"type":{"type":"string","enum":["permanent","transient","undetermined"],"description":"`permanent`, `transient` or `undetermined`."},"sub_type":{"type":"string","description":"The provider's finer classification of the bounce."},"diagnostic_code":{"type":["string","null"],"description":"What the receiving server answered. `null`: not reported."}},"required":["type","sub_type","diagnostic_code"]},"complaint":{"type":"object","properties":{"feedback_type":{"type":["string","null"],"description":"The kind of complaint the mailbox provider reported. `null`: not reported."},"sub_type":{"type":["string","null"],"description":"The provider's finer classification. `null`: not reported."}},"required":["feedback_type","sub_type"]},"delay":{"type":"object","properties":{"type":{"type":"string","description":"The provider's reason for the delay."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the provider stops trying. `null`: not reported."},"diagnostic_code":{"type":["string","null"],"description":"What the receiving server answered. `null`: not reported."}},"required":["type","expires_at","diagnostic_code"]},"delivery":{"type":"object","properties":{"smtp_response":{"type":["string","null"],"description":"What the receiving server answered. `null`: not reported."}},"required":["smtp_response"]},"failure":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"]},"suppression":{"type":"object","properties":{"id":{"type":"string","description":"The suppression's id."},"scope":{"type":"string","description":"What it covers: every email, every marketing email, or one category."},"reason":{"type":"string","enum":["bounce","complaint","manual","import","unsubscribe"],"description":"`bounce`: added after a permanent bounce. `complaint`: added after a spam complaint. `manual`: added one by one through the API or dashboard. `import`: added by a bulk import. `unsubscribe`: added by the recipient's one-click unsubscribe, scoped to the email's category."}},"required":["id","scope","reason"],"description":"Only for `email.suppressed`: the entry that matched the recipient."},"unsubscribe":{"type":"object","properties":{"contact_id":{"type":["string","null"],"description":"The contact who unsubscribed. `null`: none."},"topic":{"type":["string","null"],"description":"The topic they left. `null`: marketing altogether."}},"required":["contact_id","topic"],"description":"Only for `email.suppressed` without `suppression`: the recipient is a contact who unsubscribed (from marketing, or from the email's topic, `topic`)."},"open":{"type":"object","properties":{"user_agent":{"type":["string","null"],"description":"The client's `User-Agent`. `null`: not sent."}},"required":["user_agent"],"description":"Only for `email.opened`."},"click":{"type":"object","properties":{"url":{"type":"string","description":"The original link that was clicked."},"link_position":{"type":"integer","description":"Index of the link among the email's tracked links."},"user_agent":{"type":["string","null"],"description":"The client's `User-Agent`. `null`: not sent."}},"required":["url","link_position","user_agent"],"description":"Only for `email.clicked`."},"reschedule":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","description":"The new time."},"previous_scheduled_at":{"type":"string","format":"date-time","description":"The time it replaced."}},"required":["scheduled_at","previous_scheduled_at"],"description":"Only for `email.rescheduled`."},"email_id":{"type":"string"},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"required":["name","value"]}},"category":{"type":["string","null"]},"sandbox":{"type":"boolean"},"recipient":{"type":["string","null"]},"occurred_at":{"type":"string","format":"date-time"},"subaccount_id":{"type":"string","description":"Only for an email sent for a sub-account: its id."},"traceparent":{"type":"string","pattern":"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$","description":"Only for an email sent with a W3C `traceparent` header: that trace context (normalized to version `00`), also sent as this request's `traceparent` header, so handling the event joins the sender's trace.","examples":["00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"]}},"required":["email_id","from","to","subject","tags","category","sandbox","recipient","occurred_at"]}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","object":"event","type":"email.delivered","api_version":"2026-10-10","created_at":"2026-10-10T12:00:03.000Z","data":{"email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <onboarding@acme.com>","to":["user@example.com"],"subject":"Welcome to Acme","tags":[{"name":"template","value":"welcome"}],"category":"onboarding","sandbox":false,"recipient":"user@example.com","occurred_at":"2026-10-10T12:00:02.000Z","delivery":{"smtp_response":"250 2.0.0 OK"}}}]},"ReceivedEmailWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, and the `webhook-id` header.","examples":["evt_01k7c8m4r0c2b8w9y3d5f6g7h9"]},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["email.received"]},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"received_email_id":{"type":"string"},"from":{"type":["string","null"]},"to":{"type":"array","items":{"type":"string"}},"recipients":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"message_id":{"type":["string","null"]},"attachment_count":{"type":"integer"},"size":{"type":"integer"},"spam":{"type":"boolean"},"verdicts":{"$ref":"#/components/schemas/ReceivedEmailVerdicts"},"sandbox":{"type":"boolean"},"received_at":{"type":"string","format":"date-time"}},"required":["received_email_id","from","to","recipients","subject","message_id","attachment_count","size","spam","verdicts","sandbox","received_at"]}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4r0c2b8w9y3d5f6g7h9","object":"event","type":"email.received","api_version":"2026-10-10","created_at":"2026-10-10T12:00:01.000Z","data":{"received_email_id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Jane Doe <jane@example.com>","to":["support@inbound.acme.com"],"recipients":["support@inbound.acme.com"],"subject":"Re: Your order","message_id":"<CAF3k2m9qp4ld8sv@mail.example.com>","attachment_count":1,"size":61432,"spam":false,"verdicts":{"spam":"pass","virus":"pass","spf":"pass","dkim":"pass","dmarc":"pass","dmarc_policy":null},"sandbox":false,"received_at":"2026-10-10T12:00:00.000Z"}}]},"ReceivedEmailVerdicts":{"type":"object","properties":{"spam":{"anyOf":[{"type":"string","enum":["pass","fail","gray","processing_failed"]},{"type":"null"}],"description":"The spam verdict."},"virus":{"anyOf":[{"type":"string","enum":["pass","fail","gray","processing_failed"]},{"type":"null"}],"description":"The virus verdict."},"spf":{"anyOf":[{"type":"string","enum":["pass","fail","gray","processing_failed"]},{"type":"null"}],"description":"The SPF verdict."},"dkim":{"anyOf":[{"type":"string","enum":["pass","fail","gray","processing_failed"]},{"type":"null"}],"description":"The DKIM verdict."},"dmarc":{"anyOf":[{"type":"string","enum":["pass","fail","gray","processing_failed"]},{"type":"null"}],"description":"The DMARC verdict."},"dmarc_policy":{"type":["string","null"],"description":"The sender domain's DMARC policy (`none`, `quarantine` or `reject`) when DMARC failed."}},"required":["spam","virus","spf","dkim","dmarc","dmarc_policy"],"description":"What the receiving server concluded: `pass`, `fail`, `gray` (could not decide) or `processing_failed`; `null` when the check did not run.","examples":[{"spam":"pass","virus":"pass","spf":"pass","dkim":"pass","dmarc":"pass","dmarc_policy":null}]},"DomainWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, and the `webhook-id` header.","examples":["evt_01k7c8m4r0c2b8w9y3d5f6g7j1"]},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["domain.dmarc_report_received"]},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"organization_id":{"type":"string"},"domain_id":{"type":"string"},"domain":{"type":"string"},"dmarc_report_id":{"type":"string"},"reporter":{"type":"string","description":"The reporting organization (`org_name`)."},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"messages":{"type":"integer"},"passing":{"type":"integer"},"occurred_at":{"type":"string","format":"date-time"}},"required":["organization_id","domain_id","domain","dmarc_report_id","reporter","period_start","period_end","messages","passing","occurred_at"]}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4r0c2b8w9y3d5f6g7j1","object":"event","type":"domain.dmarc_report_received","api_version":"2026-10-10","created_at":"2026-10-10T03:12:45.000Z","data":{"organization_id":"org_01k7c8m4q2f3e9v6t5r1n0p8yz","domain_id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","domain":"acme.com","dmarc_report_id":"dmarcrep_01k7c8m4q2f3e9v6t5r1n0p8yz","reporter":"google.com","period_start":"2026-10-09T00:00:00.000Z","period_end":"2026-10-09T23:59:59.000Z","messages":1204,"passing":1200,"occurred_at":"2026-10-10T03:12:44.000Z"}}]},"AccountWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","example":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz"},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["account.reputation_warning","account.reputation_recovered","account.suspended","account.reinstated","account.marketing_paused","account.marketing_reinstated"]},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`."},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"organization_id":{"type":"string"},"status":{"type":"string","enum":["good","warning","suspended"]},"previous_status":{"type":"string","enum":["good","warning","suspended"]},"reason":{"type":["string","null"]},"occurred_at":{"type":"string","format":"date-time"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/ReputationCheck"}},"marketing":{"$ref":"#/components/schemas/MarketingStanding"}},"required":["organization_id","status","previous_status","reason","occurred_at","checks","marketing"]}},"required":["id","object","type","api_version","created_at","data"]},"ReputationCheck":{"type":"object","properties":{"trigger":{"type":"string","description":"What was measured, e.g. `bounce_rate` or `complaint_rate`.","example":"bounce_rate"},"severity":{"type":"string","enum":["ok","warning","suspend"],"description":"`ok`, `warning` (at or above the warning threshold) or `suspend` (at or above the suspension threshold)."},"message":{"type":"string"},"rate":{"type":["number","null"],"description":"`count / volume`; `null` with no volume."},"count":{"type":"integer","description":"Matching recipients, e.g. permanent bounces."},"volume":{"type":"integer","description":"Recipients sent to (live environments) in the window."},"warning_threshold":{"type":["number","null"]},"suspend_threshold":{"type":["number","null"]},"minimum_volume":{"type":["integer","null"],"description":"Below this volume the rate is reported but never acted on."}},"required":["trigger","severity","message","rate","count","volume","warning_threshold","suspend_threshold","minimum_volume"]},"MarketingStanding":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"],"description":"`active`, or `paused`: the marketing stream's bounce or complaint rate reached its suspension threshold, so marketing sends are refused until coss.com support lifts the pause. Transactional email is unaffected."},"reason":{"type":["string","null"],"description":"The trigger behind a pause.","example":"marketing_complaint_rate"},"paused_at":{"type":["string","null"],"format":"date-time"}},"required":["status","reason","paused_at"]},"SubaccountWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header."},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["subaccount.reputation_warning","subaccount.reputation_recovered","subaccount.paused","subaccount.reinstated"],"description":"What changed for the sub-account."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"subaccount_id":{"type":"string","description":"The sub-account's id."},"uid":{"type":["string","null"],"description":"Your own id for it. `null`: none."},"status":{"type":"string","enum":["good","warning","paused"],"description":"Its status after this event."},"previous_status":{"type":"string","enum":["good","warning","paused"],"description":"Its status before."},"trigger":{"type":["string","null"],"description":"What changed it: a check (`bounce_rate`, `complaint_rate`), `content_screening` or `reinstated`."},"occurred_at":{"type":"string","format":"date-time","description":"When this happened."},"checks":{"type":"array","items":{"$ref":"#/components/schemas/ReputationCheck"},"description":"The measurements behind the change (empty for reinstatements and screening)."}},"required":["subaccount_id","uid","status","previous_status","trigger","occurred_at","checks"],"description":"The sub-account's standing."}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","object":"event","type":"subaccount.paused","api_version":"2026-10-01","created_at":"2026-01-15T09:30:00.000Z","data":{"subaccount_id":"sub_01k7c8m4q2f3e9v6t5r1n0p8yz","uid":"user_8812","status":"paused","previous_status":"warning","trigger":"bounce_rate","occurred_at":"2026-01-15T09:30:00.000Z","checks":[{"trigger":"bounce_rate","severity":"suspend","message":"Bounce rate 9.50% is at or above the 8.00% suspension threshold.","rate":0.095,"count":19,"volume":200,"warning_threshold":0.04,"suspend_threshold":0.08,"minimum_volume":200}]}}]},"BillingWebhookEvent":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.invoice_finalized","billing.invoice_paid","billing.invoice_voided"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"invoice":{"$ref":"#/components/schemas/InvoiceSummary"}},"required":["organization_id","occurred_at","invoice"]}},"required":["id","object","api_version","created_at","type","data"]},{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.invoice_payment_failed"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"invoice":{"$ref":"#/components/schemas/InvoiceSummary"},"failure":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["organization_id","occurred_at","invoice","failure"]}},"required":["id","object","api_version","created_at","type","data"]},{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.plan_changed"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"change":{"type":"string","enum":["upgrade","downgrade","cancellation","reverted","contract"],"description":"`upgrade` (in effect now), `downgrade`/`cancellation` (scheduled), `reverted` (a scheduled change was undone), `contract` (a contract changed)."},"plan":{"type":"string","enum":["free","pro","scale","enterprise"],"description":"The plan from `effective_at`."},"previous_plan":{"type":"string","enum":["free","pro","scale","enterprise"]},"effective_at":{"type":"string","format":"date-time"}},"required":["organization_id","occurred_at","change","plan","previous_plan","effective_at"]}},"required":["id","object","api_version","created_at","type","data"]},{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.usage_threshold_reached"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"percent":{"type":"integer","description":"The threshold crossed, e.g. 80."},"of":{"type":"string","enum":["credit","allowance"],"description":"`credit`: the month's usage credit; `allowance`: a capped plan's included units."},"meter":{"type":["string","null"],"enum":["email.recipients","email.dedicated_ip","email.attachment_data","email.received","email.received_data","email.inboxes","sms.segments","sms.received_segments","sms.numbers","sms.registrations","sign.completed_requests","risk.phone_checks","risk.assessments","risk.content_checks","verify.verifications","verify.sms","forms.submissions","forms.file_uploads","scheduling.bookings","scheduling.hosts","hooks.messages",null],"description":"The allowance's meter (`of: allowance`)."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"When the period starts (inclusive)."},"end":{"type":"string","format":"date-time","description":"When the period ends (exclusive)."}},"required":["start","end"]}},"required":["organization_id","occurred_at","percent","of","meter","period"]}},"required":["id","object","api_version","created_at","type","data"]},{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.hold_placed","billing.hold_lifted"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"reason":{"type":"string","enum":["delinquent","spend_limit","credit_limit","admin"]}},"required":["organization_id","occurred_at","reason"]}},"required":["id","object","api_version","created_at","type","data"]},{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.credit_granted"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"credit":{"$ref":"#/components/schemas/Credit"}},"required":["organization_id","occurred_at","credit"]}},"required":["id","object","api_version","created_at","type","data"]},{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.budget_threshold_reached"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"scope":{"type":"string","enum":["user","project","api_key"],"description":"What the budget is for: a member's personal API keys (`user`), a project or an API key."},"target_id":{"type":"string","description":"The user, project or API key id."},"percent":{"type":"integer","description":"The threshold crossed, e.g. 80."},"amount":{"type":"integer","description":"The monthly budget, in cents."},"spent":{"type":"integer","description":"Spent this month when it was crossed, in cents."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"When the period starts (inclusive)."},"end":{"type":"string","format":"date-time","description":"When the period ends (exclusive)."}},"required":["start","end"]}},"required":["organization_id","occurred_at","scope","target_id","percent","amount","spent","period"]}},"required":["id","object","api_version","created_at","type","data"]},{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["billing.budget_hold_placed","billing.budget_hold_lifted"]},"data":{"type":"object","properties":{"organization_id":{"type":"string","description":"The organization's id."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened: sort events by it."},"scope":{"type":"string","enum":["user","project","api_key"],"description":"What the budget is for: a member's personal API keys (`user`), a project or an API key."},"target_id":{"type":"string","description":"The user, project or API key id."}},"required":["organization_id","occurred_at","scope","target_id"]}},"required":["id","object","api_version","created_at","type","data"]}],"examples":[{"id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","object":"event","type":"billing.invoice_paid","api_version":"2026-10-10","created_at":"2026-11-01T00:21:00.000Z","data":{"organization_id":"org_01k7c8m4q2f3e9v6t5r1n0p8yz","occurred_at":"2026-11-01T00:21:00.000Z","invoice":{"object":"invoice","id":"inv_01k7c8m4q2f3e9v6t5r1n0p8yz","number":"COSS-000042","kind":"period","status":"paid","currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"subtotal":7300,"discount":0,"credit":2500,"tax":0,"total":4800,"amount_paid":4800,"amount_due":0,"collection_method":"charge_automatically","due_at":"2026-11-01T00:20:00.000Z","finalized_at":"2026-11-01T00:20:00.000Z","paid_at":"2026-11-01T00:21:00.000Z","voided_at":null,"hosted_url":"https://invoice.stripe.com/i/acct_123/test_YWNjdF8x","pdf_url":"https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf"}}}]},"InvoiceSummary":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string"},"number":{"type":["string","null"],"description":"The invoice number. `null` until it's finalized."},"kind":{"type":"string","enum":["period","plan_change","one_off","final","threshold"],"description":"`period`: a billing month. `plan_change`: a change of plan. `one_off`: a single charge. `final`: the last invoice of an account. `threshold`: usage charged early, taken off the month's invoice."},"status":{"type":"string","enum":["open","paid","void","uncollectible"],"description":"`open`: not paid yet. `paid`: settled. `void`: canceled. `uncollectible`: written off."},"currency":{"type":"string","enum":["usd"],"description":"Always `usd`."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"When the period starts (inclusive)."},"end":{"type":"string","format":"date-time","description":"When the period ends (exclusive)."}},"required":["start","end"],"description":"What period it covers."},"subtotal":{"type":"integer","description":"An amount in cents (USD)."},"discount":{"type":"integer","description":"An amount in cents (USD)."},"credit":{"type":"integer","description":"An amount in cents (USD)."},"tax":{"type":"integer","description":"An amount in cents (USD)."},"total":{"type":"integer","description":"An amount in cents (USD)."},"amount_paid":{"type":"integer","description":"An amount in cents (USD)."},"amount_due":{"type":"integer","description":"An amount in cents (USD)."},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"],"description":"`charge_automatically`: charged to the payment method. `send_invoice`: paid by `due_at`."},"due_at":{"type":["string","null"],"format":"date-time","description":"When payment is due. `null`: not set."},"finalized_at":{"type":["string","null"],"format":"date-time","description":"When it was finalized. `null`: not yet."},"paid_at":{"type":["string","null"],"format":"date-time","description":"When it was paid. `null`: not paid."},"voided_at":{"type":["string","null"],"format":"date-time","description":"When it was voided. `null`: it wasn't."},"hosted_url":{"type":["string","null"],"description":"A page to view (and pay) the invoice."},"pdf_url":{"type":["string","null"],"description":"The invoice as a PDF. `null`: not available."}},"required":["object","id","number","kind","status","currency","period","subtotal","discount","credit","tax","total","amount_paid","amount_due","collection_method","due_at","finalized_at","paid_at","voided_at","hosted_url","pdf_url"],"examples":[{"object":"invoice","id":"inv_01k7c8m4q2f3e9v6t5r1n0p8yz","number":"COSS-000042","kind":"period","status":"paid","currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"subtotal":7300,"discount":0,"credit":2500,"tax":0,"total":4800,"amount_paid":4800,"amount_due":0,"collection_method":"charge_automatically","due_at":"2026-11-01T00:20:00.000Z","finalized_at":"2026-11-01T00:20:00.000Z","paid_at":"2026-11-01T00:21:00.000Z","voided_at":null,"hosted_url":"https://invoice.stripe.com/i/acct_123/test_YWNjdF8x","pdf_url":"https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf"}]},"Credit":{"type":"object","properties":{"object":{"type":"string","enum":["credit"]},"id":{"type":"string"},"kind":{"type":"string","enum":["amount","units"],"description":"`amount`: dollars (`amount` and `remaining` in cents); `units`: free units of `meter`."},"amount":{"type":"integer","description":"How much was granted: cents, or units for a `units` credit."},"remaining":{"type":"integer","description":"How much is left, in the same unit as `amount`."},"meter":{"type":["string","null"],"enum":["email.recipients","email.dedicated_ip","email.attachment_data","email.received","email.received_data","email.inboxes","sms.segments","sms.received_segments","sms.numbers","sms.registrations","sign.completed_requests","risk.phone_checks","risk.assessments","risk.content_checks","verify.verifications","verify.sms","forms.submissions","forms.file_uploads","scheduling.bookings","scheduling.hosts","hooks.messages",null],"description":"What a `units` credit covers."},"meters":{"type":["array","null"],"items":{"type":"string","enum":["email.recipients","email.dedicated_ip","email.attachment_data","email.received","email.received_data","email.inboxes","sms.segments","sms.received_segments","sms.numbers","sms.registrations","sign.completed_requests","risk.phone_checks","risk.assessments","risk.content_checks","verify.verifications","verify.sms","forms.submissions","forms.file_uploads","scheduling.bookings","scheduling.hosts","hooks.messages"],"description":"What is counted, e.g. `email.recipients`."},"description":"What an `amount` credit pays for (`null`: any usage)."},"applies_to":{"type":"string","enum":["usage","any"],"description":"`any`: also fees and other charges."},"source":{"type":"string","enum":["fee","commitment","support","promotion","refund","sla","threshold"],"description":"Where it came from: `fee`, `commitment`, `support`, `promotion`, `refund` or `sla`."},"description":{"type":"string","description":"What it's for."},"effective_at":{"type":"string","format":"date-time","description":"When it can start being used."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When what's left expires. `null`: never."},"voided_at":{"type":["string","null"],"format":"date-time","description":"When it was voided. `null`: it wasn't."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","kind","amount","remaining","meter","meters","applies_to","source","description","effective_at","expires_at","voided_at","created_at"],"examples":[{"object":"credit","id":"bcg_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"units","amount":50000,"remaining":12000,"meter":"email.recipients","meters":null,"applies_to":"usage","source":"support","description":"Migration credit","effective_at":"2026-10-01T00:00:00.000Z","expires_at":"2027-01-01T00:00:00.000Z","voided_at":null,"created_at":"2026-10-01T09:30:00.000Z"}]},"RiskWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","example":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz"},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["risk.assessment.review","risk.assessment.reviewed"],"description":"What happened to the assessment."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`."},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"assessment_id":{"type":"string","description":"The assessment's id."},"event":{"$ref":"#/components/schemas/RiskEvent"},"event_name":{"type":["string","null"],"description":"Your name for a `custom` event. `null`: none."},"decision":{"$ref":"#/components/schemas/RiskDecision"},"score":{"type":"number","description":"0-1: how risky the signals are together."},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/RiskReason"},"description":"Why, most significant first."},"user_id":{"type":["string","null"],"description":"Your user id. `null`: none given."},"outcome":{"anyOf":[{"$ref":"#/components/schemas/RiskOutcome"},{"type":"null"}],"description":"`risk.assessment.reviewed`: the outcome that resolved the review."},"occurred_at":{"type":"string","format":"date-time","description":"When this happened."}},"required":["assessment_id","event","event_name","decision","score","reasons","user_id","outcome","occurred_at"],"description":"The assessment, without its signals."}},"required":["id","object","type","api_version","created_at","data"]},"RiskEvent":{"type":"string","enum":["signup","login","message","checkout","custom"],"description":"What is being assessed. `custom` events are named by `event_name`; velocity is counted per event."},"RiskDecision":{"type":"string","enum":["allow","review","block"],"description":"`allow`: go ahead. `review`: suspicious; let it through with limits, or hold it for a person. `block`: refuse it."},"RiskReason":{"type":"object","properties":{"code":{"type":"string","enum":["email.invalid","email.disposable","email.undeliverable","email.role_account","email.typo","email.domain_new","ip.tor","ip.vpn_network","ip.hosting_provider","ip.vpn","ip.proxy","ip.relay","ip.private","velocity.signups_per_ip_1h","velocity.signups_per_ip_24h","velocity.signups_per_subnet_1h","velocity.signups_per_email_domain_1h","velocity.signups_per_mailbox_24h","velocity.signups_per_device_24h","velocity.checkouts_per_ip_1h","velocity.checkouts_per_user_1h","velocity.checkouts_per_card_24h","velocity.logins_per_ip_1h","velocity.logins_per_user_1h","velocity.events_per_ip_1h","velocity.events_per_user_1h","duplicate.canonical_mailbox","duplicate.device","history.fraud_mailbox","history.fraud_user","history.fraud_ip","history.fraud_subnet","history.fraud_card","history.fraud_device","checkout.card_country_mismatch","checkout.billing_country_mismatch","checkout.prepaid_card","device.automation","device.invalid","login.new_country","login.new_network","captcha.failed","captcha.missing","content.spam","content.phishing","content.malware","content.fraud","rule.matched","list.blocked","list.allowed"],"description":"The reason's code, listed under Risk's reasons in the docs."},"message":{"type":"string","description":"What it means, in words. May change."},"value":{"type":"number","description":"The count behind a `velocity.*` reason, or the score behind a `content.*` one."},"threshold":{"type":"number","description":"What a `velocity.*` or `content.*` reason fires at."},"window":{"type":"string","enum":["1h","24h"],"description":"`velocity.*`: the window it's counted over."},"suggestion":{"type":"string","description":"`email.typo`: the likely domain."},"provider":{"type":"string","description":"`ip.hosting_provider`, `ip.vpn_network`: the network's operator; `ip.vpn`: the VPN service."},"previous_user":{"type":["string","null"],"description":"`duplicate.canonical_mailbox`, `duplicate.device`: your id of the user who has the mailbox or device, if known."},"previous_assessment":{"type":"string","description":"`duplicate.canonical_mailbox`, `duplicate.device`: the assessment that first saw the mailbox or device."},"entry":{"type":"string","description":"`list.*`: the matching list entry."},"rule":{"type":"string","description":"`rule.matched`: the rule's id."},"name":{"type":"string","description":"`rule.matched`: the rule's name."},"type":{"type":"string","enum":["email","domain","ip","asn","country","user"],"description":"`list.*`: what matched."}},"required":["code","message"]},"RiskOutcome":{"type":"string","enum":["legitimate","fraud","abuse"],"description":"What really happened: `legitimate`, `fraud`, or `abuse` (spam, free-tier abuse and the like)."},"HookEndpointWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, also sent as the `webhook-id` header.","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["hook_endpoint.disabled"]},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`."},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"application_id":{"type":"string"},"application_uid":{"type":["string","null"]},"endpoint_id":{"type":"string"},"url":{"type":"string"},"failing_since":{"type":"string","format":"date-time"},"occurred_at":{"type":"string","format":"date-time"}},"required":["application_id","application_uid","endpoint_id","url","failing_since","occurred_at"]}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","object":"event","type":"hook_endpoint.disabled","api_version":"2026-10-10","created_at":"2026-01-20T09:30:00.000Z","data":{"application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","application_uid":"customer_8812","endpoint_id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks","failing_since":"2026-01-15T09:30:00.000Z","occurred_at":"2026-01-20T09:30:00.000Z"}}]},"ContactWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, and the `webhook-id` header.","examples":["evt_01k7c8m4r0c2b8w9y3d5f6g7h9"]},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["contact.created","contact.updated","contact.deleted","contact.unsubscribed","contact.confirmed"],"description":"What happened to the contact."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"string","description":"The contact's id."},"email":{"type":"string","description":"The contact's address."},"status":{"type":"string","enum":["subscribed","unsubscribed","pending"],"description":"Its consent after this event."}},"required":["id","email","status"]},"source":{"type":"string","enum":["api","dashboard","import","preference_center","form"],"description":"How the contact was created."},"topic":{"type":["string","null"],"description":"`contact.unsubscribed` from one topic (its key); `null`: from marketing altogether."},"occurred_at":{"type":"string","format":"date-time","description":"When this happened."}},"required":["contact","source","topic","occurred_at"],"description":"The contact, without its properties."}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4r0c2b8w9y3d5f6g7h9","object":"event","type":"contact.created","api_version":"2026-10-10","created_at":"2026-10-10T12:00:00.000Z","data":{"contact":{"id":"contact_01k7c8m4q2f3e9v6t5r1n0p8yz","email":"ada@example.com","status":"subscribed"},"source":"api","topic":null,"occurred_at":"2026-10-10T12:00:00.000Z"}}]},"BroadcastWebhookEvent":{"type":"object","properties":{"id":{"type":"string","examples":["evt_01k7c8m4r0c2b8w9y3d5f6g7h9"]},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["broadcast.sending","broadcast.sent","broadcast.paused","broadcast.canceled","broadcast.failed"],"description":"What happened to the broadcast."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"broadcast":{"type":"object","properties":{"id":{"type":"string","description":"The broadcast's id."},"name":{"type":"string","description":"Its name."},"status":{"type":"string","enum":["draft","scheduled","sending","paused","sent","canceled","failed"],"description":"Its status after this event."}},"required":["id","name","status"]},"pause_reason":{"type":["string","null"],"description":"Why a paused broadcast waits. `null`: it isn't paused."},"error":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"],"description":"Why it failed. `null`: it didn't."},"stats":{"$ref":"#/components/schemas/BroadcastStats"},"occurred_at":{"type":"string","format":"date-time","description":"When this happened."}},"required":["broadcast","pause_reason","error","stats","occurred_at"],"description":"The broadcast and how it fared."}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4r0c2b8w9y3d5f6g7h9","object":"event","type":"broadcast.sent","api_version":"2026-10-10","created_at":"2026-10-20T09:12:40.000Z","data":{"broadcast":{"id":"bcast_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"October newsletter","status":"sent"},"pause_reason":null,"error":null,"stats":{"recipients":1200,"sent":1200,"delivered":1180,"bounced":6,"complained":1,"failed":0,"opened":540,"clicked":120,"unsubscribed":4},"occurred_at":"2026-10-20T09:12:40.000Z"}}]},"BroadcastStats":{"type":"object","properties":{"recipients":{"type":"integer","description":"Emails made so far (one per reached contact)."},"sent":{"type":"integer","description":"Emails accepted by the provider."},"delivered":{"type":"integer","description":"Emails delivered to recipients' servers."},"bounced":{"type":"integer","description":"Permanent bounces."},"complained":{"type":"integer","description":"Emails marked as spam by recipients."},"failed":{"type":"integer","description":"Emails that couldn't be sent."},"opened":{"type":"integer","description":"Emails opened at least once (with open tracking)."},"clicked":{"type":"integer","description":"Emails clicked at least once (with click tracking)."},"unsubscribed":{"type":"integer","description":"Unsubscribes through the broadcast's links."}},"required":["recipients","sent","delivered","bounced","complained","failed","opened","clicked","unsubscribed"],"description":"How its emails fared so far."},"SmsWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id: the same as `SmsEvent.id`."},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["sms.scheduled","sms.sent","sms.delivered","sms.undelivered","sms.failed","sms.suppressed","sms.canceled"],"description":"What happened to the message."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"failure":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"],"description":"Why the message failed or wasn't delivered."},"provider_error_code":{"type":["string","null"],"description":"The provider's or carrier's own error code, e.g. `30007`."},"suppression":{"type":"object","properties":{"id":{"type":"string","description":"The suppression's id."},"reason":{"type":"string","enum":["opt_out","manual","invalid_number"],"description":"Why the number is suppressed."}},"required":["id","reason"],"description":"`sms.suppressed`: the entry that made coss.com skip the number."},"sms_id":{"type":"string","description":"The id of the message."},"from":{"type":"string","description":"The number it's sent from."},"to":{"type":"string","description":"The recipient's number."},"country":{"type":"string","description":"The recipient's country (ISO 3166-1 alpha-2)."},"segments":{"type":"integer","description":"Segments the body takes (what is billed)."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The tag's name."},"value":{"type":"string","description":"The tag's value."}},"required":["name","value"]},"description":"Your tags on the message."},"sandbox":{"type":"boolean","description":"Whether it was sent from a sandbox environment: simulated."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"traceparent":{"type":"string","pattern":"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$","description":"Only for a message sent with a W3C `traceparent` header: that trace context (normalized to version `00`), also sent as this request's `traceparent` header, so handling the event joins the sender's trace.","examples":["00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"]}},"required":["sms_id","from","to","country","segments","tags","sandbox","occurred_at"]}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"smsevt_01k7c8m4r0c2b8w9y3d5f6g7h8","object":"event","type":"sms.delivered","api_version":"2026-10-10","created_at":"2026-11-10T12:00:04.100Z","data":{"sms_id":"sms_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"+14155550123","to":"+14155550199","country":"US","segments":1,"tags":[{"name":"flow","value":"sign_in"}],"sandbox":false,"occurred_at":"2026-11-10T12:00:04.000Z"}}]},"ReceivedSmsWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["sms.received","sms.opted_out","sms.opted_in"],"description":"`sms.received`: a message arrived. `sms.opted_out`: the sender replied with an opt-out keyword. `sms.opted_in`: the sender replied with an opt-in keyword."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"received_sms_id":{"type":["string","null"],"description":"The received message; `null` for an opt-out to a number whose replies go to no environment."},"from":{"type":"string","description":"Who sent it."},"to":{"type":"string","description":"Your number that received it."},"keyword":{"type":["string","null"],"enum":["stop","start","help",null],"description":"The keyword it is, if any: `stop`, `start` or `help`. `null`: none."},"sandbox":{"type":"boolean","description":"Whether it's a simulated message of a sandbox environment."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."}},"required":["received_sms_id","from","to","keyword","sandbox","occurred_at"]}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","object":"event","type":"sms.received","api_version":"2026-10-10","created_at":"2026-11-10T12:05:00.100Z","data":{"received_sms_id":"smsin_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"+14155550199","to":"+14155550123","keyword":null,"sandbox":false,"occurred_at":"2026-11-10T12:05:00.000Z"}}]},"SignRequestWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id: the same as the audit trail's `SignEvent.id`."},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["sign_request.sent","sign_request.viewed","sign_request.signer_signed","sign_request.declined","sign_request.completed","sign_request.canceled","sign_request.expired"],"description":"`sent`: sent to signers. `viewed`: a signer opened it. `signer_signed`: a signer signed. `declined`: a signer declined. `completed`: the sealed document is ready to download. `canceled` and `expired`: it ended unsigned."},"api_version":{"type":"string","description":"The API version the payload is rendered in (your endpoint's version).","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"sign_request_id":{"type":"string","description":"The signature request's id."},"status":{"type":"string","enum":["draft","sent","completed","declined","canceled","expired"],"description":"The request's status after the event."},"title":{"type":"string","description":"The request's title."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"signer":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The signer's id."},"name":{"type":"string","description":"The signer's name."},"email":{"type":"string","description":"The signer's email address."},"client_ref":{"type":["string","null"],"description":"Your own id for the signer. `null`: none given."},"status":{"type":"string","enum":["pending","notified","viewed","signed","declined"],"description":"The signer's status after the event."}},"required":["id","name","email","client_ref","status"],"description":"The signer who viewed, signed or declined; `null` otherwise."},"reason":{"type":["string","null"],"description":"A decline's reason, if the signer gave one."},"sandbox":{"type":"boolean","description":"Whether it belongs to a sandbox environment."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."}},"required":["sign_request_id","status","title","metadata","signer","reason","sandbox","occurred_at"],"description":"The request. Never documents or field values."}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"sevt_01k7c8m4q2f3e9v6t5r1n0p8yz","object":"event","type":"sign_request.signer_signed","api_version":"2026-10-10","created_at":"2026-10-26T15:10:00.100Z","data":{"sign_request_id":"sreq_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"sent","title":"Services agreement","metadata":{"deal":"D-1042"},"signer":{"id":"ssgn_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Ada Lovelace","email":"ada@example.com","client_ref":"user_42","status":"signed"},"reason":null,"sandbox":false,"occurred_at":"2026-10-26T15:10:00.000Z"}}]},"FormSubmissionWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["form.submission.received","form.submission.flagged"],"description":"`received`: a submission was accepted (at once, after the submitter confirmed, or released from review). `flagged`: Risk held it for review or refused it (honeypot catches send nothing)."},"api_version":{"type":"string","description":"The API version the payload is rendered in (your endpoint's version).","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"form_id":{"type":"string","description":"The form's id."},"form_name":{"type":"string","description":"The form's name."},"submission_id":{"type":"string","description":"The submission's id."},"status":{"type":"string","enum":["pending_confirmation","accepted","held","spam"],"description":"The submission's status after this event."},"data":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Field name → value; a field posted several times has an array."},"submitter_email":{"type":["string","null"],"description":"The value of the form's `submitter.email_field`. `null` when it has none."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmissionFile"},"description":"Uploaded files (download them with the API; never their bytes here)."},"spam_reason":{"type":["string","null"],"enum":["honeypot","risk_block","risk_review","content",null],"description":"Why it was flagged. `null`: not flagged."},"sandbox":{"type":"boolean","description":"Whether it belongs to a sandbox environment."},"occurred_at":{"type":"string","format":"date-time","description":"When this happened."}},"required":["form_id","form_name","submission_id","status","data","submitter_email","files","spam_reason","sandbox","occurred_at"],"description":"The submission."}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01kd2m9a0b1c2d3e4f5g6h7j8p","object":"event","type":"form.submission.received","api_version":"2026-10-10","created_at":"2026-10-29T10:00:00.100Z","data":{"form_id":"form_01kd2m8n3p4q5r6s7t8v9w0x1y","form_name":"Contact us","submission_id":"fsub_01kd2m9a0b1c2d3e4f5g6h7j8k","status":"accepted","data":{"name":"Ada Lovelace","email":"ada@example.com","message":"Hello!"},"submitter_email":"ada@example.com","files":[],"spam_reason":null,"sandbox":false,"occurred_at":"2026-10-29T10:00:00.000Z"}}]},"FormSubmissionFile":{"type":"object","properties":{"id":{"type":"string","examples":["ffile_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"field":{"type":"string","description":"The form field it was uploaded through."},"filename":{"type":"string","description":"The file's name, made safe."},"content_type":{"type":"string","description":"The MIME type it was uploaded as."},"size":{"type":"integer","description":"Bytes."}},"required":["id","field","filename","content_type","size"]},"SchedulingBookingWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this payload is rendered in: the endpoint's."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"type":{"type":"string","enum":["scheduling.booking.created","scheduling.booking.pending_approval","scheduling.booking.confirmed","scheduling.booking.rescheduled","scheduling.booking.cancelled","scheduling.booking.declined","scheduling.booking.no_show","scheduling.booking.external_conflict","scheduling.booking.calendar_write_failed","scheduling.booking.location_ready","scheduling.booking.reassigned","scheduling.booking.started","scheduling.booking.ended","scheduling.booking.reminder"],"description":"What happened to the booking."},"data":{"$ref":"#/components/schemas/SchedulingBookingWebhookData"}},"required":["id","object","api_version","created_at","type","data"],"examples":[{"id":"evt_01kd2m9a0b1c2d3e4f5g6h7j8m","object":"event","type":"scheduling.booking.confirmed","api_version":"2026-10-10","created_at":"2027-01-01T10:00:00.000Z","data":{"booking_id":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type_id":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"confirmed","start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z","host_ids":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"],"attendee_uids":["patient_77"],"series_id":null,"occurred_at":"2027-01-01T10:00:00.000Z"}}]},"SchedulingBookingWebhookData":{"type":"object","properties":{"booking_id":{"type":"string","description":"The booking's id."},"event_type_id":{"type":"string","description":"The booked event type's id."},"status":{"type":"string","enum":["held","pending_approval","confirmed","cancelled","declined"],"description":"The booking's status after this event."},"start":{"type":"string","description":"When the booking starts."},"end":{"type":"string","description":"When the booking ends."},"host_ids":{"type":"array","items":{"type":"string"},"description":"The ids of the hosts taking it."},"attendee_uids":{"type":"array","items":{"type":"string"},"description":"Your uids of its attendees."},"series_id":{"type":["string","null"],"description":"The id of its series. `null`: not part of one."},"previous_start":{"type":"string","description":"`scheduling.booking.rescheduled`: when it used to start."},"previous_host_ids":{"type":"array","items":{"type":"string"},"description":"On `scheduling.booking.reassigned`: who had it before."},"reassignment_id":{"type":"string","description":"On `scheduling.booking.reassigned`: the bulk reassignment it was part of."},"reminder":{"type":"object","properties":{"key":{"type":"string","description":"Which reminder this is."},"anchor":{"type":"string","enum":["start","end","confirmed","rescheduled","cancelled","declined","pending_approval","no_show"],"description":"The moment it's timed from."},"before_minutes":{"type":["number","null"],"description":"How long before the anchor. `null` when it's after."},"after_minutes":{"type":["number","null"],"description":"How long after the anchor. `null` when it's before."},"scheduled_for":{"type":"string","description":"When it was due."}},"required":["key","anchor","before_minutes","after_minutes","scheduled_for"],"description":"`scheduling.booking.reminder`: which reminder this is."},"occurred_at":{"type":"string","description":"When this happened."}},"required":["booking_id","event_type_id","status","start","end","host_ids","attendee_uids","series_id","occurred_at"],"description":"Ids, times and statuses only. Retrieve the booking for anything about the person."},"SchedulingCalendarDelegationWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this payload is rendered in: the endpoint's."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"type":{"type":"string","enum":["scheduling.calendar_delegation.failing","scheduling.calendar_delegation.restored"]},"data":{"type":"object","properties":{"delegation_id":{"type":"string"},"provider":{"type":"string"},"domain":{"type":"string"},"code":{"type":["string","null"],"description":"What the provider said, when it refused."},"occurred_at":{"type":"string"}},"required":["delegation_id","provider","domain","code","occurred_at"]}},"required":["id","object","api_version","created_at","type","data"],"examples":[{"id":"evt_01kd2m9a0b1c2d3e4f5g6h7j8m","object":"event","type":"scheduling.calendar_delegation.failing","api_version":"2026-10-10","created_at":"2027-01-01T10:00:00.000Z","data":{"delegation_id":"caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","domain":"example.com","code":"unauthorized_client","occurred_at":"2027-01-01T10:00:00.000Z"}}]},"SchedulingCalendarWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this payload is rendered in: the endpoint's."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"type":{"type":"string","enum":["scheduling.calendar.connected","scheduling.calendar.needs_reauth","scheduling.calendar.disconnected"],"description":"`connected`: a calendar account was connected. `needs_reauth`: access was lost, and the host isn't offered until it's back. `disconnected`: the connection was removed."},"data":{"type":"object","properties":{"host_id":{"type":"string","description":"The host's id."},"connection_id":{"type":"string","description":"The calendar connection's id."},"provider":{"type":"string","description":"The calendar provider, such as `google`."},"occurred_at":{"type":"string","description":"When this happened."}},"required":["host_id","connection_id","provider","occurred_at"],"description":"The host and calendar connection this is about."}},"required":["id","object","api_version","created_at","type","data"],"examples":[{"id":"evt_01kd2m9a0b1c2d3e4f5g6h7j8m","object":"event","type":"scheduling.calendar.needs_reauth","api_version":"2026-10-10","created_at":"2027-01-01T10:00:00.000Z","data":{"host_id":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","connection_id":"calconn_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","occurred_at":"2027-01-01T10:00:00.000Z"}}]},"SchedulingOutOfOfficeWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this payload is rendered in: the endpoint's."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"type":{"type":"string","enum":["scheduling.out_of_office.created","scheduling.out_of_office.updated","scheduling.out_of_office.deleted","scheduling.out_of_office.started","scheduling.out_of_office.ended"]},"data":{"type":"object","properties":{"out_of_office_id":{"type":"string"},"host_id":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"group":{"type":["string","null"]},"occurred_at":{"type":"string"}},"required":["out_of_office_id","host_id","start","end","group","occurred_at"]}},"required":["id","object","api_version","created_at","type","data"],"examples":[{"id":"evt_01kd2m9a0b1c2d3e4f5g6h7j8m","object":"event","type":"scheduling.out_of_office.created","api_version":"2026-10-10","created_at":"2027-01-01T10:00:00.000Z","data":{"out_of_office_id":"ooo_01kd2m9a0b1c2d3e4f5g6h7j8m","host_id":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","start":"2027-08-02T04:00:00.000Z","end":"2027-08-14T04:00:00.000Z","group":null,"occurred_at":"2027-01-01T10:00:00.000Z"}}]},"SchedulingReassignmentWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this payload is rendered in: the endpoint's."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"type":{"type":"string","enum":["scheduling.reassignment.completed"]},"data":{"type":"object","properties":{"reassignment_id":{"type":"string"},"status":{"type":"string","enum":["completed","cancelled"]},"out_of_office_id":{"type":["string","null"]},"counts":{"type":"object","properties":{"total":{"type":"number"},"pending":{"type":"number"},"reassigned":{"type":"number"},"skipped":{"type":"number","description":"They'd moved on since it was selected."},"no_candidate":{"type":"number","description":"Nobody could take them: they stayed."},"failed":{"type":"number"},"cancelled":{"type":"number"}},"required":["total","pending","reassigned","skipped","no_candidate","failed","cancelled"]},"occurred_at":{"type":"string"}},"required":["reassignment_id","status","out_of_office_id","counts","occurred_at"]}},"required":["id","object","api_version","created_at","type","data"],"examples":[{"id":"evt_01kd2m9a0b1c2d3e4f5g6h7j8m","object":"event","type":"scheduling.reassignment.completed","api_version":"2026-10-10","created_at":"2027-01-01T10:00:00.000Z","data":{"reassignment_id":"reasn_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"completed","out_of_office_id":null,"counts":{"total":12,"pending":0,"reassigned":11,"skipped":0,"no_candidate":1,"failed":0,"cancelled":0},"occurred_at":"2027-01-01T10:00:00.000Z"}}]},"SchedulingOauthAppWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id."},"object":{"type":"string","enum":["event"]},"api_version":{"type":"string","description":"The API version this payload is rendered in: the endpoint's."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"type":{"type":"string","enum":["scheduling.oauth_app.failing","scheduling.oauth_app.restored"]},"data":{"type":"object","properties":{"oauth_app_id":{"type":"string"},"provider":{"type":"string"},"code":{"type":["string","null"],"description":"What the provider said, when it refused."},"occurred_at":{"type":"string"}},"required":["oauth_app_id","provider","code","occurred_at"]}},"required":["id","object","api_version","created_at","type","data"],"examples":[{"id":"whev_01kd2m9a0b1c2d3e4f5g6h7j8m","object":"event","type":"scheduling.oauth_app.failing","created_at":"2027-01-01T10:00:00.000Z","data":{"oauth_app_id":"calapp_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","code":"app_refused","occurred_at":"2027-01-01T10:00:00.000Z"}}]},"Environment":{"type":"object","properties":{"object":{"type":"string","enum":["environment"]},"id":{"type":"string","description":"The environment's id."},"name":{"type":"string","description":"The environment's name."},"slug":{"type":"string","description":"The environment's slug, as in dashboard URLs."},"mode":{"type":"string","enum":["live","sandbox"],"description":"`live` delivers email; `sandbox` (`coss_test_` keys) never does."},"project":{"type":"object","properties":{"id":{"type":"string","description":"The project's id."},"name":{"type":"string","description":"The project's name."},"slug":{"type":"string","description":"The project's slug, as in dashboard URLs."}},"required":["id","name","slug"],"additionalProperties":false,"description":"The project it belongs to."},"organization":{"type":"object","properties":{"id":{"type":"string","description":"The organization's id."},"name":{"type":"string","description":"The organization's name."},"slug":{"type":"string","description":"The organization's slug, as in dashboard URLs."},"api_version":{"type":"string","description":"The organization's pinned API version: what requests without a `Coss-Version` header and new webhook endpoints get."},"hipaa_mode":{"type":"boolean","description":"Whether the organization is in HIPAA mode, which refuses some requests with `hipaa_mode_restriction`. Its compliance settings page lists what the mode changes."}},"required":["id","name","slug","api_version","hipaa_mode"],"additionalProperties":false,"description":"The organization it belongs to."},"api_key":{"type":"object","properties":{"id":{"type":"string","description":"The key's id."},"name":{"type":["string","null"],"description":"The key's name. `null`: none."},"start":{"type":["string","null"],"description":"The key's first characters, as shown in the dashboard."},"access":{"type":"string","enum":["full","restricted"],"description":"`full`: every permission, including ones new products add later. `restricted`: only `permissions`, chosen when the key was created."},"permissions":{"type":"array","items":{"type":"string"},"description":"What the key may do now, as `resource:action` (the names `insufficient_permissions` errors use), e.g. `email:send`."}},"required":["id","name","start","access","permissions"],"additionalProperties":false,"description":"The API key making this request."}},"required":["object","id","name","slug","mode","project","organization","api_key"],"additionalProperties":false,"description":"The environment an API key belongs to, with its project and organization.","examples":[{"object":"environment","id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Development","slug":"development","mode":"sandbox","project":{"id":"proj_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Default","slug":"default"},"organization":{"id":"org_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Acme","slug":"acme","api_version":"2026-10-10"},"api_key":{"id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Backend","start":"coss_test_Ab","access":"restricted","permissions":["email:send","email:read"]}}]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","idempotency_error","rate_limit_error","billing_error","api_error"]},"code":{"type":"string","description":"Machine-readable reason, e.g. `invalid_api_key`."},"message":{"type":"string","description":"Human-readable explanation. May change."},"param":{"type":"string","description":"The request field or header the error relates to."},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, e.g. `to.1`."},"message":{"type":"string"}},"required":["path","message"]},"description":"Every problem: of the request (`validation_error`) or of a template (`invalid_template_variables`, `template_invalid`)."},"hint":{"type":"string","description":"What to try next. Present when coss.com can name a fix, and often includes a docs URL."},"request_id":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"required":["type","code","message","request_id"]}},"required":["error"]},"DeletedApiKey":{"type":"object","properties":{"object":{"type":"string","enum":["api_key"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"additionalProperties":false,"examples":[{"object":"api_key","id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"OidcAccessToken":{"type":"object","properties":{"object":{"type":"string","enum":["oidc_access_token"]},"access_token":{"type":"string","description":"Use it as an API key (`Authorization: Bearer …`) until it expires. It can do what the credential allows, in the credential's environment."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Seconds until it expires."},"expires_at":{"type":"string","description":"When it expires (ISO 8601)."},"environment_id":{"type":"string","description":"The environment it works in."}},"required":["object","access_token","token_type","expires_in","expires_at","environment_id"],"additionalProperties":false,"description":"A short-lived access token exchanged for an OIDC ID token.","examples":[{"object":"oidc_access_token","access_token":"coss_live_oidc_3q2-7wEVR6aZ1xYb0pN4kL8sT5uC9dF2gH6jM1nP0rQ","token_type":"Bearer","expires_in":3600,"expires_at":"2026-11-13T13:00:00.000Z","environment_id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz"}]},"ExchangeOidcTokenBody":{"type":"object","properties":{"credential_id":{"type":"string","minLength":1,"maxLength":64,"description":"The OIDC credential to exchange through (`oidc_…`, shown on the environment's API keys page). Not a secret: it can live in a workflow file."},"token":{"type":"string","minLength":1,"maxLength":16384,"description":"The OIDC ID token your CI or hosting provider issued to this job or function (a JWT)."}},"required":["credential_id","token"],"additionalProperties":false,"examples":[{"credential_id":"oidc_01k7c8m4q2f3e9v6t5r1n0p8yz","token":"eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9.eyJpc3MiOiIuLi4ifQ.c2lnbmF0dXJl"}]},"Email":{"type":"object","properties":{"object":{"type":"string","enum":["email"]},"id":{"type":"string","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"from":{"type":"string","description":"Who it's sent from."},"to":{"type":"array","items":{"type":"string"},"description":"The `To` addresses."},"cc":{"type":"array","items":{"type":"string"},"description":"The `Cc` addresses."},"bcc":{"type":"array","items":{"type":"string"},"description":"The `Bcc` addresses."},"reply_to":{"type":"array","items":{"type":"string"},"description":"The `Reply-To` addresses."},"subject":{"type":"string","description":"The subject, rendered if it came from a template."},"html":{"type":["string","null"],"description":"The HTML part. `null`: none, or the body was discarded."},"text":{"type":["string","null"],"description":"The plain text part. `null`: none, or the body was discarded."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"The custom headers it was sent with."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The tag's name."},"value":{"type":"string","description":"The tag's value."}},"required":["name","value"]},"description":"Your tags on the email."},"category":{"type":["string","null"],"description":"The email's category, which suppressions and tracking rules can scope to. `null`: none."},"stream":{"type":"string","enum":["transactional","marketing"],"description":"`transactional` or `marketing`."},"status":{"type":"string","enum":["queued","sent","failed","scheduled","canceled"],"description":"Whether the email was handed to the delivery provider. `scheduled` emails wait for `scheduled_at`; `canceled` ones were canceled before that. Per-recipient delivery is in `recipients`."},"failure":{"anyOf":[{"$ref":"#/components/schemas/EmailFailure"},{"type":"null"}],"description":"Why the email failed; `null` unless `status` is `failed`."},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/EmailRecipient"},"description":"Each recipient, with how delivery to them went."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/EmailAttachment"},"description":"Attachment metadata. Content is never returned, and is discarded once sent."},"sandbox":{"type":"boolean","description":"True when sent from a sandbox environment (never delivered)."},"tracking":{"$ref":"#/components/schemas/EmailTracking"},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time","description":"When it was handed to the provider. `null`: not yet."},"scheduled_at":{"type":["string","null"],"format":"date-time","description":"When the email was scheduled to be sent; `null` if it was not."},"batch_id":{"type":["string","null"],"description":"The batch that sent the email; `null` if it was sent on its own."},"template":{"anyOf":[{"$ref":"#/components/schemas/EmailTemplateReference"},{"type":"null"}],"description":"The template the email was rendered from; `null` if it was sent without one."},"broadcast_id":{"type":["string","null"],"description":"The broadcast the email is part of; `null` for any other email."},"subaccount_id":{"type":["string","null"],"description":"The sub-account the email was sent for; `null` if it was sent for none."},"content_storage":{"$ref":"#/components/schemas/EmailContentStorage"}},"required":["object","id","from","to","cc","bcc","reply_to","subject","html","text","headers","tags","category","stream","status","failure","recipients","attachments","sandbox","tracking","created_at","sent_at","scheduled_at","batch_id","template","broadcast_id","subaccount_id","content_storage"],"examples":[{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <onboarding@acme.com>","to":["user@example.com"],"cc":[],"bcc":[],"reply_to":[],"subject":"Welcome to Acme","html":"<p>Thanks for signing up!</p>","text":null,"headers":{},"tags":[{"name":"template","value":"welcome"}],"category":"onboarding","stream":"transactional","status":"sent","failure":null,"recipients":[{"address":"user@example.com","type":"to","status":"delivered","last_event_at":"2026-10-10T12:00:02.000Z"}],"sandbox":false,"tracking":{"opens":false,"clicks":false,"unsubscribe":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null},"attachments":[],"created_at":"2026-10-10T12:00:00.000Z","sent_at":"2026-10-10T12:00:01.000Z","scheduled_at":null,"batch_id":null,"template":null,"broadcast_id":null,"subaccount_id":null,"content_storage":{"mode":"store","discarded_at":null}}]},"EmailFailure":{"type":"object","properties":{"code":{"type":"string","description":"Why the email failed, e.g. `all_recipients_suppressed`, `domain_not_verified`, `content_rejected`, `attachments_unavailable`, `dispatch_failed` or `provider_error`.","examples":["all_recipients_suppressed"]},"message":{"type":"string"}},"required":["code","message"],"examples":[{"code":"all_recipients_suppressed","message":"Every recipient is on the suppression list or unsubscribed."}]},"EmailRecipient":{"type":"object","properties":{"address":{"type":"string","description":"The bare, lower-cased address."},"type":{"type":"string","enum":["to","cc","bcc"],"description":"Which list it's on: `to`, `cc` or `bcc`."},"status":{"type":"string","enum":["queued","sent","delivery_delayed","delivered","bounced","suppressed","complained","failed","canceled"],"description":"Delivery status of this recipient. `suppressed` means the address is on the environment's suppression list (for every email or for this email's category), so it was skipped. `canceled` means the scheduled email was canceled before it was sent."},"last_event_at":{"type":["string","null"],"format":"date-time","description":"When its latest delivery event happened. `null`: none yet."}},"required":["address","type","status","last_event_at"],"description":"One recipient of an email and how delivery to them went.","examples":[{"address":"user@example.com","type":"to","status":"delivered","last_event_at":"2026-10-10T12:00:02.000Z"}]},"EmailAttachment":{"type":"object","properties":{"id":{"type":"string","example":"att_01k7c8m4q2f3e9v6t5r1n0p8yz"},"filename":{"type":"string"},"content_type":{"type":"string"},"content_id":{"type":["string","null"],"description":"Set for inline attachments (`cid:` references)."},"size":{"type":"integer","description":"Size in bytes."}},"required":["id","filename","content_type","content_id","size"]},"EmailTracking":{"type":"object","properties":{"opens":{"type":"boolean","description":"Whether opens are tracked for this email."},"clicks":{"type":"boolean","description":"Whether link clicks are tracked for this email."},"unsubscribe":{"type":"boolean","description":"Whether the email carries one-click unsubscribe headers (RFC 8058)."},"open_count":{"type":"integer","description":"Times opened. Mail clients that prefetch images inflate it."},"first_opened_at":{"type":["string","null"],"format":"date-time","description":"When it was first opened. `null`: not yet."},"last_opened_at":{"type":["string","null"],"format":"date-time","description":"When it was last opened. `null`: not yet."},"click_count":{"type":"integer","description":"Link clicks. Link scanners inflate it."},"first_clicked_at":{"type":["string","null"],"format":"date-time","description":"When a link was first clicked. `null`: not yet."},"last_clicked_at":{"type":["string","null"],"format":"date-time","description":"When a link was last clicked. `null`: not yet."}},"required":["opens","clicks","unsubscribe","open_count","first_opened_at","last_opened_at","click_count","first_clicked_at","last_clicked_at"],"examples":[{"opens":false,"clicks":false,"unsubscribe":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null}],"description":"Open and click tracking, as resolved when the email was sent, with engagement so far. Opens can be inflated by mail clients that prefetch images, clicks by link scanners."},"EmailTemplateReference":{"type":"object","properties":{"id":{"type":"string","description":"The template's id."},"version":{"type":["integer","null"],"description":"`null` for a dashboard test send of the draft."},"locale":{"type":"string","description":"The locale the email was rendered in."}},"required":["id","version","locale"],"examples":[{"id":"etpl_01k7c8m4q2f3e9v6t5r1n0p8yz","version":2,"locale":"en"}]},"EmailContentStorage":{"type":"object","properties":{"mode":{"type":"string","enum":["store","discard"],"description":"The environment's content storage when the email was sent. With `discard`, the subject, `html`, `text`, `headers`, template variables and attachment filenames are cleared once the email is sent, fails or is canceled."},"discarded_at":{"type":["string","null"],"format":"date-time","description":"When the content was cleared; `null` while it is kept. A cleared email has an empty `subject`, `html` and `text` `null` and no `headers`."}},"required":["mode","discarded_at"],"examples":[{"mode":"store","discarded_at":null}],"description":"Whether coss.com keeps the email's content after sending it."},"SendEmailRequest":{"type":"object","properties":{"from":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"to":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":1,"maxItems":50}],"description":"Who it goes to."},"cc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}],"description":"Who it's copied to."},"bcc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}],"description":"Who it's blind copied to."},"reply_to":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}],"description":"Where replies go."},"subject":{"type":"string","minLength":1,"maxLength":998,"description":"Required unless the email is sent from a template (`template_id`)."},"html":{"type":"string","description":"HTML body. Provide `html`, `text`, or both."},"text":{"type":"string","description":"Plain-text body. Without it, an `html` email goes out with a text part generated from the HTML."},"template_id":{"type":"string","minLength":1,"maxLength":100,"description":"Send a published email template (its id or alias) instead of `subject`, `html` and `text`.","examples":["welcome"]},"template_version":{"type":"integer","minimum":1,"description":"A published version of the template to send. Defaults to the latest one."},"locale":{"type":"string","maxLength":35,"description":"The template locale to send, e.g. \"pt-BR\". Falls back to the language (\"pt\"), then to the template's default locale.","examples":["en"]},"variables":{"type":"object","additionalProperties":{},"examples":[{"first_name":"Ada"}],"description":"Values for the template's variables, keyed by name."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Up to 15 custom headers. Names are case-insensitive."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's name, unique on the email."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's value."}},"required":["name","value"],"additionalProperties":false},"maxItems":50,"description":"Your tags on the email."},"category":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"What kind of email this is, e.g. \"marketing\". Recipients suppressed for this category (or for every email) are skipped."},"scheduled_at":{"type":"string","format":"date-time","description":"Send the email at this time instead of now (ISO 8601 with an offset, at most 30 days ahead). A time that is not in the future sends immediately. Scheduled emails can be rescheduled or canceled until they are sent.","example":"2026-10-11T09:00:00Z"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SendEmailAttachment"},"maxItems":20,"description":"Up to 20 files, at most 25 MB combined."},"tracking":{"$ref":"#/components/schemas/TrackingOptions"},"stream":{"type":"string","enum":["transactional","marketing"],"description":"`transactional` (the default) or `marketing`. Marketing email goes out on its own sending infrastructure and reputation, so its complaints never hold up transactional mail. It needs the environment's postal address (marketing settings), exactly one recipient, and no `List-Unsubscribe` header: coss.com adds one-click unsubscribe headers and a footer with the address and an unsubscribe link (place them yourself with `{{{unsubscribe_url}}}`, `{{{preferences_url}}}` and `{{{mailing_address}}}`). Contacts who unsubscribed are skipped."},"subaccount":{"type":"string","minLength":1,"maxLength":256,"description":"Send for one of your sub-accounts (email for platforms): its id (`sub_…`) or your `uid` for it. The email then counts toward its quotas and reputation, skips its suppressions (and the environment's), and must come from one of its domains or a domain you share with sub-accounts. Transactional email only.","examples":["user_8812"]}},"required":["from","to"],"additionalProperties":false,"examples":[{"from":"Acme <onboarding@acme.com>","to":"user@example.com","subject":"Welcome to Acme","html":"<p>Thanks for signing up!</p>","tags":[{"name":"template","value":"welcome"}],"category":"onboarding"},{"from":"Acme <onboarding@acme.com>","to":"user@example.com","template_id":"welcome","locale":"de","variables":{"first_name":"Ada"}}]},"SendEmailAttachment":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"content":{"type":"string","minLength":1,"description":"The file's bytes, base64-encoded."},"content_type":{"type":"string","pattern":"^[!#$%&'*+.^_`|~0-9A-Za-z-]+\\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$","description":"Defaults from the filename's extension."},"content_id":{"type":"string","pattern":"^[A-Za-z0-9!#$%&'*+\\-./=?^_`{|}~@]{1,100}$","description":"Makes the attachment inline: reference it from `html` as `<img src=\"cid:logo@acme\">`."}},"required":["filename","content"],"additionalProperties":false},"TrackingOptions":{"type":"object","properties":{"opens":{"type":"boolean","description":"Add an invisible pixel to the HTML body and record `email.opened` events."},"clicks":{"type":"boolean","description":"Send HTML links through a coss.com redirect and record `email.clicked` events. Links with a `data-coss-no-track` attribute are left alone."},"unsubscribe":{"type":"boolean","description":"Add one-click unsubscribe headers (`List-Unsubscribe` and `List-Unsubscribe-Post`, RFC 8058). An unsubscribe suppresses the recipient for this email's category and records `email.unsubscribed`. Needs a `category`, a single recipient, no `List-Unsubscribe` header of your own and at most 13 custom headers."}},"additionalProperties":false,"description":"Overrides the environment's tracking settings (its default, or the rule for this email's category) for this email. Omitted fields keep the configured setting."},"EmailBatch":{"type":"object","properties":{"object":{"type":"string","enum":["email_batch"]},"id":{"type":"string","examples":["batch_01k8d0n6x5f3w2e1r9t7y4u6i8"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Email"},"description":"The batch's emails, in the order of the request."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","data","created_at"],"examples":[{"object":"email_batch","id":"batch_01k8d0n6x5f3w2e1r9t7y4u6i8","data":[{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <notifications@acme.com>","to":["ada@example.com"],"cc":[],"bcc":[],"reply_to":[],"subject":"Your weekly summary","html":"<p>Hi Ada, here is your week.</p>","text":null,"headers":{},"tags":[],"category":"digest","stream":"transactional","status":"queued","failure":null,"recipients":[{"address":"ada@example.com","type":"to","status":"queued","last_event_at":null}],"sandbox":false,"tracking":{"opens":false,"clicks":false,"unsubscribe":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null},"attachments":[],"created_at":"2026-10-10T12:00:00.000Z","sent_at":null,"scheduled_at":null,"batch_id":"batch_01k8d0n6x5f3w2e1r9t7y4u6i8","template":null,"broadcast_id":null,"subaccount_id":null,"content_storage":{"mode":"store","discarded_at":null}}],"created_at":"2026-10-10T12:00:00.000Z"}]},"SendEmailBatchRequest":{"type":"object","properties":{"emails":{"type":"array","items":{"$ref":"#/components/schemas/SendEmailRequest"},"minItems":1,"maxItems":100,"description":"Up to 100 emails, each accepted by `POST /v1/emails`. The batch is accepted or rejected as a whole."}},"required":["emails"],"additionalProperties":false,"examples":[{"emails":[{"from":"Acme <notifications@acme.com>","to":"ada@example.com","subject":"Your weekly summary","html":"<p>Hi Ada, here is your week.</p>","category":"digest"},{"from":"Acme <notifications@acme.com>","to":"grace@example.com","subject":"Your weekly summary","html":"<p>Hi Grace, here is your week.</p>","category":"digest"}]}]},"EmailSummaryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailSummary"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <onboarding@acme.com>","to":["user@example.com"],"cc":[],"bcc":[],"reply_to":[],"subject":"Welcome to Acme","tags":[{"name":"template","value":"welcome"}],"category":"onboarding","status":"sent","failure":null,"recipients":[{"address":"user@example.com","type":"to","status":"delivered","last_event_at":"2026-10-10T12:00:02.000Z"}],"sandbox":false,"tracking":{"opens":false,"clicks":false,"unsubscribe":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null},"created_at":"2026-10-10T12:00:00.000Z","sent_at":"2026-10-10T12:00:01.000Z","scheduled_at":null,"batch_id":null,"template":null,"subaccount_id":null,"content_storage":{"mode":"store","discarded_at":null}}],"has_more":false}]},"EmailSummary":{"type":"object","properties":{"object":{"type":"string","enum":["email"]},"id":{"type":"string","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"from":{"type":"string","description":"Who it's sent from."},"to":{"type":"array","items":{"type":"string"},"description":"The `To` addresses."},"cc":{"type":"array","items":{"type":"string"},"description":"The `Cc` addresses."},"bcc":{"type":"array","items":{"type":"string"},"description":"The `Bcc` addresses."},"reply_to":{"type":"array","items":{"type":"string"},"description":"The `Reply-To` addresses."},"subject":{"type":"string","description":"The subject, rendered if it came from a template."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The tag's name."},"value":{"type":"string","description":"The tag's value."}},"required":["name","value"]},"description":"Your tags on the email."},"category":{"type":["string","null"],"description":"The email's category, which suppressions and tracking rules can scope to. `null`: none."},"stream":{"type":"string","enum":["transactional","marketing"],"description":"`transactional` or `marketing`."},"status":{"type":"string","enum":["queued","sent","failed","scheduled","canceled"],"description":"Whether the email was handed to the delivery provider. `scheduled` emails wait for `scheduled_at`; `canceled` ones were canceled before that. Per-recipient delivery is in `recipients`."},"failure":{"anyOf":[{"$ref":"#/components/schemas/EmailFailure"},{"type":"null"}],"description":"Why the email failed; `null` unless `status` is `failed`."},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/EmailRecipient"},"description":"Each recipient, with how delivery to them went."},"sandbox":{"type":"boolean","description":"True when sent from a sandbox environment (never delivered)."},"tracking":{"$ref":"#/components/schemas/EmailTracking"},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time","description":"When it was handed to the provider. `null`: not yet."},"scheduled_at":{"type":["string","null"],"format":"date-time","description":"When the email was scheduled to be sent; `null` if it was not."},"batch_id":{"type":["string","null"],"description":"The batch that sent the email; `null` if it was sent on its own."},"template":{"anyOf":[{"$ref":"#/components/schemas/EmailTemplateReference"},{"type":"null"}],"description":"The template the email was rendered from; `null` if it was sent without one."},"broadcast_id":{"type":["string","null"],"description":"The broadcast the email is part of; `null` for any other email."},"subaccount_id":{"type":["string","null"],"description":"The sub-account the email was sent for; `null` if it was sent for none."},"content_storage":{"$ref":"#/components/schemas/EmailContentStorage"}},"required":["object","id","from","to","cc","bcc","reply_to","subject","tags","category","stream","status","failure","recipients","sandbox","tracking","created_at","sent_at","scheduled_at","batch_id","template","broadcast_id","subaccount_id","content_storage"],"description":"An email without its content. Retrieve the email for `html`, `text`, `headers` and `attachments`.","examples":[{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <onboarding@acme.com>","to":["user@example.com"],"cc":[],"bcc":[],"reply_to":[],"subject":"Welcome to Acme","tags":[{"name":"template","value":"welcome"}],"category":"onboarding","status":"sent","failure":null,"recipients":[{"address":"user@example.com","type":"to","status":"delivered","last_event_at":"2026-10-10T12:00:02.000Z"}],"sandbox":false,"tracking":{"opens":false,"clicks":false,"unsubscribe":false,"open_count":0,"first_opened_at":null,"last_opened_at":null,"click_count":0,"first_clicked_at":null,"last_clicked_at":null},"created_at":"2026-10-10T12:00:00.000Z","sent_at":"2026-10-10T12:00:01.000Z","scheduled_at":null,"batch_id":null,"template":null,"subaccount_id":null,"content_storage":{"mode":"store","discarded_at":null}}]},"RescheduleEmailRequest":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","description":"The new time to send the email at (ISO 8601 with an offset, at most 30 days ahead). A time that is not in the future sends it right away.","example":"2026-10-12T09:00:00Z"}},"required":["scheduled_at"],"additionalProperties":false,"examples":[{"scheduled_at":"2026-10-12T09:00:00Z"}]},"EmailEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailEvent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"email_event","id":"evt_01k7c8m4r0c2b8w9y3d5f6g7h8","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"email.sent","recipient":null,"occurred_at":"2026-10-10T12:00:01.000Z","data":{}},{"object":"email_event","id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"email.delivered","recipient":"user@example.com","occurred_at":"2026-10-10T12:00:02.000Z","data":{"delivery":{"smtp_response":"250 2.0.0 OK"}}}],"has_more":false}]},"EmailEvent":{"type":"object","properties":{"object":{"type":"string","enum":["email_event"]},"id":{"type":"string","examples":["evt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"email_id":{"type":"string","description":"The email's id."},"type":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","email.unsubscribed"],"description":"What happened, such as `email.delivered` or `email.bounced`."},"recipient":{"type":["string","null"],"description":"The recipient this event is about; `null` for the whole email."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"data":{"$ref":"#/components/schemas/EmailEventData"}},"required":["object","id","email_id","type","recipient","occurred_at","data"],"examples":[{"object":"email_event","id":"evt_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"email.delivered","recipient":"user@example.com","occurred_at":"2026-10-10T12:00:02.000Z","data":{"delivery":{"smtp_response":"250 2.0.0 OK"}}}]},"EmailEventData":{"type":"object","properties":{"bounce":{"type":"object","properties":{"type":{"type":"string","enum":["permanent","transient","undetermined"],"description":"`permanent`, `transient` or `undetermined`."},"sub_type":{"type":"string","description":"The provider's finer classification of the bounce."},"diagnostic_code":{"type":["string","null"],"description":"What the receiving server answered. `null`: not reported."}},"required":["type","sub_type","diagnostic_code"]},"complaint":{"type":"object","properties":{"feedback_type":{"type":["string","null"],"description":"The kind of complaint the mailbox provider reported. `null`: not reported."},"sub_type":{"type":["string","null"],"description":"The provider's finer classification. `null`: not reported."}},"required":["feedback_type","sub_type"]},"delay":{"type":"object","properties":{"type":{"type":"string","description":"The provider's reason for the delay."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the provider stops trying. `null`: not reported."},"diagnostic_code":{"type":["string","null"],"description":"What the receiving server answered. `null`: not reported."}},"required":["type","expires_at","diagnostic_code"]},"delivery":{"type":"object","properties":{"smtp_response":{"type":["string","null"],"description":"What the receiving server answered. `null`: not reported."}},"required":["smtp_response"]},"failure":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"]},"suppression":{"type":"object","properties":{"id":{"type":"string","description":"The suppression's id."},"scope":{"type":"string","description":"What it covers: every email, every marketing email, or one category."},"reason":{"type":"string","enum":["bounce","complaint","manual","import","unsubscribe"],"description":"`bounce`: added after a permanent bounce. `complaint`: added after a spam complaint. `manual`: added one by one through the API or dashboard. `import`: added by a bulk import. `unsubscribe`: added by the recipient's one-click unsubscribe, scoped to the email's category."}},"required":["id","scope","reason"],"description":"Only for `email.suppressed`: the entry that matched the recipient."},"unsubscribe":{"type":"object","properties":{"contact_id":{"type":["string","null"],"description":"The contact who unsubscribed. `null`: none."},"topic":{"type":["string","null"],"description":"The topic they left. `null`: marketing altogether."}},"required":["contact_id","topic"],"description":"Only for `email.suppressed` without `suppression`: the recipient is a contact who unsubscribed (from marketing, or from the email's topic, `topic`)."},"open":{"type":"object","properties":{"user_agent":{"type":["string","null"],"description":"The client's `User-Agent`. `null`: not sent."}},"required":["user_agent"],"description":"Only for `email.opened`."},"click":{"type":"object","properties":{"url":{"type":"string","description":"The original link that was clicked."},"link_position":{"type":"integer","description":"Index of the link among the email's tracked links."},"user_agent":{"type":["string","null"],"description":"The client's `User-Agent`. `null`: not sent."}},"required":["url","link_position","user_agent"],"description":"Only for `email.clicked`."},"reschedule":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","description":"The new time."},"previous_scheduled_at":{"type":"string","format":"date-time","description":"The time it replaced."}},"required":["scheduled_at","previous_scheduled_at"],"description":"Only for `email.rescheduled`."}},"description":"Details of the event: only what its `type` has.","examples":[{"delivery":{"smtp_response":"250 2.0.0 OK"}}]},"EmailLinkList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailLink"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"email_link","id":"lnk_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","position":0,"url":"https://acme.com/start","click_count":0,"first_clicked_at":null,"last_clicked_at":null}],"has_more":false}]},"EmailLink":{"type":"object","properties":{"object":{"type":"string","enum":["email_link"]},"id":{"type":"string","examples":["lnk_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"email_id":{"type":"string","description":"The email's id."},"position":{"type":"integer","description":"Index of the link among the tracked links."},"url":{"type":"string","description":"The original link."},"click_count":{"type":"integer","description":"Times it was clicked. Link scanners inflate it."},"first_clicked_at":{"type":["string","null"],"format":"date-time","description":"When it was first clicked. `null`: not yet."},"last_clicked_at":{"type":["string","null"],"format":"date-time","description":"When it was last clicked. `null`: not yet."}},"required":["object","id","email_id","position","url","click_count","first_clicked_at","last_clicked_at"],"examples":[{"object":"email_link","id":"lnk_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","position":0,"url":"https://acme.com/start","click_count":0,"first_clicked_at":null,"last_clicked_at":null}]},"EmailTemplate":{"type":"object","properties":{"object":{"type":"string","enum":["email_template"]},"id":{"type":"string","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"alias":{"type":["string","null"],"description":"A name to send the template by instead of its id. `null`: none."},"name":{"type":"string","description":"Shown in the dashboard."},"description":{"type":["string","null"],"description":"Your note about it. `null`: none."},"published_version":{"type":["integer","null"],"description":"The version sends use; `null` until the draft is first published."},"published_at":{"type":["string","null"],"format":"date-time","description":"When the published version was published. `null`: never."},"has_unpublished_changes":{"type":"boolean","description":"Whether the draft was changed since it was last published."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","alias","name","description","published_version","published_at","has_unpublished_changes","created_at","updated_at"],"examples":[{"object":"email_template","id":"etpl_01k7c8m4q2f3e9v6t5r1n0p8yz","alias":"welcome","name":"Welcome","description":"Sent after sign-up.","published_version":2,"published_at":"2026-10-10T12:00:00.000Z","has_unpublished_changes":false,"created_at":"2026-10-01T09:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"CreateEmailTemplateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Shown in the dashboard."},"alias":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$","description":"A name to send the template by instead of its id, e.g. `welcome`: the same alias can be used in every environment.","examples":["welcome"]},"description":{"type":"string","maxLength":500,"description":"Your note about it, shown in the dashboard."},"default_locale":{"type":"string","maxLength":35,"description":"The locale sends fall back to when they ask for none, or for one without content. Defaults to the first entry of `contents` (or \"en\").","examples":["en"]},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariableInput"},"maxItems":50,"description":"The variables the template uses, with their types."},"sample_variables":{"type":"object","additionalProperties":{},"examples":[{"first_name":"Ada"}],"description":"Example values for previews and test sends in the dashboard."},"contents":{"type":"array","items":{"$ref":"#/components/schemas/TemplateContentInput"},"maxItems":30,"description":"The subject, HTML and text per locale."}},"required":["name"],"additionalProperties":false,"description":"Creates the template and its draft. Publish the draft to send it.","examples":[{"name":"Welcome","alias":"welcome","default_locale":"en","variables":[{"name":"first_name","type":"string","required":true}],"sample_variables":{"first_name":"Ada"},"contents":[{"locale":"en","subject":"Welcome, {{first_name}}","html":"<p>Hi {{first_name}}, thanks for signing up!</p>"},{"locale":"de","subject":"Willkommen, {{first_name}}","html":"<p>Hallo {{first_name}}, danke für deine Anmeldung!</p>"}]}]},"TemplateVariableInput":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]{0,63}$","description":"Used in the template as `{{name}}`."},"type":{"type":"string","enum":["string","number","boolean","list"],"description":"`string`, `number`, `boolean`, or `list` (an array of objects with the declared `fields`, looped over with `{{#each name}}`)."},"required":{"type":"boolean","default":true,"description":"Sends must pass it unless it has a `default`. Defaults to true."},"default":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Used when a send leaves it out. Not for lists."},"description":{"type":"string","maxLength":500,"description":"What it's for, shown in the dashboard."},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]{0,63}$","description":"Used inside `{{#each}}` as `{{name}}`."},"type":{"type":"string","enum":["string","number","boolean"],"description":"The field's type."},"required":{"type":"boolean","default":true,"description":"Whether each item must have it. Defaults to true."}},"required":["name","type"],"additionalProperties":false},"minItems":1,"maxItems":20,"description":"A list's item fields (required for lists, only for lists)."}},"required":["name","type"],"additionalProperties":false},"TemplateContentInput":{"type":"object","properties":{"locale":{"type":"string","maxLength":35,"description":"The BCP 47 language tag this content is for, unique in `contents`.","examples":["en"]},"subject":{"type":"string","minLength":1,"maxLength":2000,"description":"The subject template."},"html":{"type":["string","null"],"maxLength":524288,"description":"The HTML template. Provide `html`, `text`, or both."},"text":{"type":["string","null"],"maxLength":262144,"description":"The plain-text template."}},"required":["locale","subject"],"additionalProperties":false},"EmailTemplateList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailTemplate"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"email_template","id":"etpl_01k7c8m4q2f3e9v6t5r1n0p8yz","alias":"welcome","name":"Welcome","description":"Sent after sign-up.","published_version":2,"published_at":"2026-10-10T12:00:00.000Z","has_unpublished_changes":false,"created_at":"2026-10-01T09:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"UpdateEmailTemplateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Shown in the dashboard."},"alias":{"anyOf":[{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$","description":"A name to send the template by instead of its id, e.g. `welcome`: the same alias can be used in every environment.","examples":["welcome"]},{"type":"null"}],"description":"`null` removes the alias."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Your note about it. `null` removes it."}},"additionalProperties":false,"description":"Changes the template's name, alias or description. Content changes go to the draft.","examples":[{"name":"Welcome (new users)"}]},"DeletedEmailTemplate":{"type":"object","properties":{"object":{"type":"string","enum":["email_template"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"email_template","id":"etpl_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"EmailTemplateVersion":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_version"]},"template_id":{"type":"string","description":"The template's id."},"version":{"type":["integer","null"],"description":"The version number; `null` for the draft."},"revision":{"type":"integer","description":"Counts the draft's saves. A published version keeps the revision it was published from."},"default_locale":{"type":"string","description":"The locale sends fall back to when they ask for none, or for one without content."},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariable"},"description":"The variables the template uses, with their types."},"sample_variables":{"type":"object","additionalProperties":{},"description":"Example values for previews and test sends in the dashboard."},"contents":{"type":"array","items":{"$ref":"#/components/schemas/TemplateContent"},"description":"The subject, HTML and text per locale."},"problems":{"type":"array","items":{"$ref":"#/components/schemas/TemplateProblem"},"description":"Syntax errors and undeclared variables per locale and field, which keep a draft from being published. Always empty for published versions."},"published_at":{"type":["string","null"],"format":"date-time","description":"When this version was published. `null` for the draft."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","template_id","version","revision","default_locale","variables","sample_variables","contents","problems","published_at","created_at","updated_at"],"examples":[{"object":"email_template_version","template_id":"etpl_01k7c8m4q2f3e9v6t5r1n0p8yz","version":2,"revision":3,"default_locale":"en","variables":[{"name":"first_name","type":"string","required":true}],"sample_variables":{"first_name":"Ada"},"contents":[{"locale":"en","subject":"Welcome, {{first_name}}","html":"<p>Hi {{first_name}}, thanks for signing up!</p>","text":null}],"problems":[],"published_at":"2026-10-10T12:00:00.000Z","created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"TemplateVariable":{"type":"object","properties":{"name":{"type":"string","description":"Used in the template as `{{name}}`."},"type":{"type":"string","enum":["string","number","boolean","list"],"description":"`string`, `number`, `boolean`, or `list` (an array of objects with the declared `fields`)."},"required":{"type":"boolean","description":"Whether sends must pass it, unless it has a `default`."},"default":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Used when a send leaves it out."},"description":{"type":"string","description":"What it's for, shown in the dashboard."},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Used inside `{{#each}}` as `{{name}}`."},"type":{"type":"string","enum":["string","number","boolean"],"description":"The field's type."},"required":{"type":"boolean","description":"Whether each item must have it."}},"required":["name","type","required"]},"description":"A list's item fields."}},"required":["name","type","required"],"examples":[{"name":"first_name","type":"string","required":true}]},"TemplateContent":{"type":"object","properties":{"locale":{"type":"string","description":"The BCP 47 language tag this content is for."},"subject":{"type":"string","description":"The subject template."},"html":{"type":["string","null"],"description":"The HTML template. `null`: text only."},"text":{"type":["string","null"],"description":"The plain-text template. `null`: HTML only."}},"required":["locale","subject","html","text"],"examples":[{"locale":"en","subject":"Welcome, {{first_name}}","html":"<p>Hi {{first_name}}, thanks for signing up!</p>","text":null}]},"TemplateProblem":{"type":"object","properties":{"locale":{"type":"string","description":"The locale whose content it's in."},"field":{"type":"string","enum":["subject","html","text"],"description":"The part of the content it's in."},"message":{"type":"string","description":"What's wrong."},"line":{"type":"integer","description":"The line it's on, from 1."},"column":{"type":"integer","description":"The column it's at, from 1."}},"required":["locale","field","message","line","column"]},"UpdateEmailTemplateDraftRequest":{"type":"object","properties":{"revision":{"type":"integer","minimum":1,"description":"The draft `revision` you read. When given, the request is refused (`template_revision_mismatch`) if the draft changed since."},"default_locale":{"type":"string","maxLength":35,"description":"The locale sends fall back to when they ask for none, or for one without content. Defaults to the first entry of `contents` (or \"en\").","examples":["en"]},"variables":{"type":"array","items":{"$ref":"#/components/schemas/TemplateVariableInput"},"maxItems":50,"description":"The variables the template uses, with their types."},"sample_variables":{"type":"object","additionalProperties":{},"examples":[{"first_name":"Ada"}],"description":"Example values for previews and test sends in the dashboard."},"contents":{"type":"array","items":{"$ref":"#/components/schemas/TemplateContentInput"},"maxItems":30,"description":"The subject, HTML and text per locale."}},"additionalProperties":false,"description":"Replaces the whole draft: fields left out are emptied (`default_locale` falls back to the first locale).","examples":[{"revision":3,"default_locale":"en","variables":[{"name":"first_name","type":"string","required":true}],"sample_variables":{"first_name":"Ada"},"contents":[{"locale":"en","subject":"Welcome, {{first_name}}","html":"<p>Hi {{first_name}}, thanks for signing up!</p>"},{"locale":"de","subject":"Willkommen, {{first_name}}","html":"<p>Hallo {{first_name}}, danke für deine Anmeldung!</p>"}]}]},"PublishEmailTemplateRequest":{"type":"object","properties":{"revision":{"type":"integer","minimum":1,"description":"The draft `revision` you read. When given, the request is refused (`template_revision_mismatch`) if the draft changed since."}},"additionalProperties":false,"examples":[{"revision":3}]},"RenderedEmailTemplate":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_render"]},"template_id":{"type":"string","description":"The template's id."},"version":{"type":["integer","null"],"description":"The version rendered; `null` for the draft."},"locale":{"type":"string","description":"The locale rendered."},"subject":{"type":"string","description":"The rendered subject."},"html":{"type":["string","null"],"description":"The rendered HTML. `null`: the template has none."},"text":{"type":["string","null"],"description":"The rendered plain text. `null`: the template has none."}},"required":["object","template_id","version","locale","subject","html","text"],"examples":[{"object":"email_template_render","template_id":"etpl_01k7c8m4q2f3e9v6t5r1n0p8yz","version":null,"locale":"en","subject":"Welcome, Ada","html":"<p>Hi Ada, thanks for signing up!</p>","text":null}]},"RenderEmailTemplateRequest":{"type":"object","properties":{"version":{"type":"integer","minimum":1,"description":"A published version to render. Default: the draft."},"locale":{"type":"string","maxLength":35,"description":"The locale to render, e.g. \"pt-BR\". Falls back to the language (\"pt\"), then to the default locale, as sends do.","examples":["en"]},"variables":{"type":"object","additionalProperties":{},"examples":[{"first_name":"Ada"}],"description":"Values by variable name, checked as a send checks them. Default: `sample_variables`."}},"additionalProperties":false,"description":"What to render: nothing is sent or stored.","examples":[{"locale":"en","variables":{"first_name":"Ada"}}]},"EmailTemplateVersionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailTemplateVersion"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"email_template_version","template_id":"etpl_01k7c8m4q2f3e9v6t5r1n0p8yz","version":2,"revision":3,"default_locale":"en","variables":[{"name":"first_name","type":"string","required":true}],"sample_variables":{"first_name":"Ada"},"contents":[{"locale":"en","subject":"Welcome, {{first_name}}","html":"<p>Hi {{first_name}}, thanks for signing up!</p>","text":null}],"problems":[],"published_at":"2026-10-10T12:00:00.000Z","created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"Domain":{"type":"object","properties":{"object":{"type":"string","enum":["domain"]},"id":{"type":"string","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"name":{"type":"string","description":"The domain, lower-cased.","examples":["acme.com"]},"status":{"type":"string","enum":["pending","verified","temporary_failure","failed","deleting"],"description":"`pending` while the records are being checked, `verified` once they are, `temporary_failure` after a transient DNS problem, and `failed` when verification gave up (72 hours) — restart it with the verify endpoint. `deleting` is a removal in progress."},"can_send":{"type":"boolean","description":"Whether live keys may send from this domain right now."},"region":{"type":["string","null"],"description":"The provider region it sends from. `null`: not set up there."},"mail_from_domain":{"type":"string","description":"The envelope sender subdomain bounces come back to."},"mail_from_status":{"type":"string","enum":["pending","success","temporary_failure","failed"],"description":"How setting up its bounce-handling `MAIL FROM` domain went."},"records":{"type":"array","items":{"$ref":"#/components/schemas/DomainRecord"},"description":"The DNS records to publish, with the result of the last check."},"created_at":{"type":"string","format":"date-time"},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When DNS was last checked. `null`: not yet."},"verified_at":{"type":["string","null"],"format":"date-time","description":"When it was verified. `null`: it isn't."},"failed_at":{"type":["string","null"],"format":"date-time","description":"When verification failed. `null`: it hasn't."},"tracking":{"anyOf":[{"$ref":"#/components/schemas/TrackingDomain"},{"type":"null"}]},"receiving":{"anyOf":[{"$ref":"#/components/schemas/ReceivingDomain"},{"type":"null"}]},"bimi":{"$ref":"#/components/schemas/DomainBimi"},"subaccount_id":{"type":["string","null"],"description":"The sub-account the domain belongs to (only it sends from it, with its own reputation); `null` for the organization's own."},"shared_with_subaccounts":{"type":"boolean","description":"An organization's domain its sub-accounts may send from too."}},"required":["object","id","name","status","can_send","region","mail_from_domain","mail_from_status","records","created_at","last_checked_at","verified_at","failed_at","tracking","receiving","bimi","subaccount_id","shared_with_subaccounts"],"examples":[{"object":"domain","id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"acme.com","status":"verified","can_send":true,"region":"us-east-1","mail_from_domain":"send.acme.com","mail_from_status":"success","records":[{"priority":null,"required":true,"status":"verified","found":[],"purpose":"dkim","type":"CNAME","name":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com","value":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"},{"priority":10,"required":true,"status":"verified","found":[],"purpose":"mail_from_mx","type":"MX","name":"send.acme.com","value":"feedback-smtp.us-east-1.amazonses.com"},{"priority":null,"required":true,"status":"verified","found":[],"purpose":"mail_from_spf","type":"TXT","name":"send.acme.com","value":"v=spf1 include:amazonses.com ~all"},{"priority":null,"required":false,"status":"verified","found":[],"purpose":"dmarc","type":"TXT","name":"_dmarc.acme.com","value":"v=DMARC1; p=none;"}],"created_at":"2026-01-15T09:30:00.000Z","last_checked_at":"2026-01-15T09:42:10.000Z","verified_at":"2026-01-15T09:42:10.000Z","failed_at":null,"tracking":{"hostname":"links.acme.com","status":"active","record":{"type":"CNAME","name":"links.acme.com","value":"track.cosslinks.com","status":"verified","found":[]},"message":null,"created_at":"2026-01-15T09:45:00.000Z","last_checked_at":"2026-01-15T09:52:00.000Z","activated_at":"2026-01-15T09:52:00.000Z","failed_at":null},"receiving":null,"bimi":{"status":"configured","name":"default._bimi.acme.com","record":"v=BIMI1; l=https://acme.com/brand/logo.svg; a=https://acme.com/brand/vmc.pem","logo_url":"https://acme.com/brand/logo.svg","certificate_url":"https://acme.com/brand/vmc.pem","dmarc_policy":"reject","issues":[]},"subaccount_id":null,"shared_with_subaccounts":false}]},"DomainRecord":{"type":"object","properties":{"purpose":{"type":"string","enum":["dkim","mail_from_mx","mail_from_spf","dmarc"],"description":"What the record is for: `dkim` signs messages, `mail_from_mx` and `mail_from_spf` set up the bounce subdomain, `dmarc` is recommended but not required."},"type":{"type":"string","enum":["CNAME","MX","TXT"]},"name":{"type":"string","description":"The fully qualified record name to create."},"value":{"type":"string"},"priority":{"type":["integer","null"],"description":"`MX` records only."},"required":{"type":"boolean","description":"`false` for records that are only recommended."},"status":{"type":"string","enum":["verified","missing","mismatch","not_checked"],"description":"What the last DNS check saw. `not_checked` means DNS has not been consulted yet."},"found":{"type":"array","items":{"type":"string"},"description":"What DNS returned when it did not match."}},"required":["purpose","type","name","value","priority","required","status","found"],"examples":[{"priority":null,"required":true,"status":"verified","found":[],"purpose":"dkim","type":"CNAME","name":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com","value":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"}]},"TrackingDomain":{"type":"object","properties":{"hostname":{"type":"string","description":"The tracking hostname, a subdomain of the domain.","examples":["links.acme.com"]},"status":{"type":"string","enum":["pending","active","temporary_failure","failed","deleting"],"description":"`pending` until the CNAME points at coss.com and its certificate is issued, `active` once links and open pixels of emails sent from the domain use it, `temporary_failure` when an active hostname stopped working (emails fall back to the default tracking host meanwhile), `failed` when setup gave up (72 hours) — restart it with the domain's verify endpoint. `deleting` is a removal in progress."},"record":{"type":"object","properties":{"type":{"type":"string","enum":["CNAME"],"description":"The record's type."},"name":{"type":"string","description":"The fully qualified record name to create."},"value":{"type":"string","description":"The host the record must point at."},"status":{"type":"string","enum":["verified","missing","mismatch","not_checked"],"description":"What the last DNS check saw. `not_checked` means DNS has not been consulted yet."},"found":{"type":"array","items":{"type":"string"},"description":"What DNS returned when it did not match."}},"required":["type","name","value","status","found"],"description":"The DNS record to publish, with the result of the last check."},"message":{"type":["string","null"],"description":"What is holding the hostname up, when the certificate provider said."},"created_at":{"type":"string","format":"date-time"},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When it was last checked. `null`: not yet."},"activated_at":{"type":["string","null"],"format":"date-time","description":"When it became active. `null`: it isn't."},"failed_at":{"type":["string","null"],"format":"date-time","description":"When it failed. `null`: it hasn't."}},"required":["hostname","status","record","message","created_at","last_checked_at","activated_at","failed_at"],"description":"A domain's custom tracking domain: open pixels and click redirects of emails sent from the domain use it while it is `active`.","examples":[{"hostname":"links.acme.com","status":"active","record":{"type":"CNAME","name":"links.acme.com","value":"track.cosslinks.com","status":"verified","found":[]},"message":null,"created_at":"2026-01-15T09:45:00.000Z","last_checked_at":"2026-01-15T09:52:00.000Z","activated_at":"2026-01-15T09:52:00.000Z","failed_at":null}]},"ReceivingDomain":{"type":"object","properties":{"hostname":{"type":"string","description":"The hostname that receives email: the domain itself or a subdomain of it.","examples":["inbound.acme.com"]},"environment_id":{"type":"string","description":"The environment its received emails are delivered to.","examples":["env_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"record":{"type":"object","properties":{"type":{"type":"string","enum":["MX"],"description":"The record's type."},"name":{"type":"string","description":"The fully qualified record name to create."},"value":{"type":"string","description":"The mail exchange the record must point at."},"priority":{"type":"integer","description":"The MX record's priority."},"status":{"type":"string","enum":["verified","missing","mismatch","not_checked"],"description":"What the last DNS check saw: `verified` once the most preferred MX records point at coss.com. `not_checked` means DNS has not been consulted yet."},"found":{"type":"array","items":{"type":"string"},"description":"What DNS returned when it did not match."}},"required":["type","name","value","priority","status","found"],"description":"The MX record to publish, with the result of the last check. Mail for the hostname is received as soon as it reaches coss.com; the check only shows what DNS serves."},"created_at":{"type":"string","format":"date-time"},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When it was last checked. `null`: not yet."}},"required":["hostname","environment_id","record","created_at","last_checked_at"],"description":"A domain's receiving hostname: email sent to any address at it becomes a received email of its environment.","examples":[{"hostname":"inbound.acme.com","environment_id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz","record":{"type":"MX","name":"inbound.acme.com","value":"inbound-smtp.us-east-1.amazonaws.com","priority":10,"status":"verified","found":[]},"created_at":"2026-01-15T09:45:00.000Z","last_checked_at":"2026-01-15T09:52:00.000Z"}]},"DomainBimi":{"type":"object","properties":{"status":{"type":"string","enum":["not_checked","missing","invalid","configured"],"description":"`configured` when the BIMI record is valid and DMARC is enforced, `invalid` when a record exists but something is wrong (see `issues`), `missing` when there is no record, and `not_checked` until DNS has been consulted. coss.com checks DNS only: mailbox providers still validate the logo and the certificate."},"name":{"type":"string","description":"Where the BIMI record was found, or looked up when there is none: `default._bimi.<domain>`, or the organizational domain's when only it has one."},"record":{"type":["string","null"],"description":"The `v=BIMI1` record found."},"logo_url":{"type":["string","null"],"description":"The record's logo URL (`l=`)."},"certificate_url":{"type":["string","null"],"description":"The record's VMC or CMC certificate URL (`a=`)."},"dmarc_policy":{"type":["string","null"],"enum":["none","quarantine","reject",null],"description":"The DMARC policy that applies to the domain (the organizational domain's `sp` when it has no record of its own), `null` without a DMARC record."},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["dmarc_missing","dmarc_not_enforced","dmarc_partial","record_multiple","record_invalid","logo_missing","logo_not_https","certificate_missing","certificate_not_https"]},"message":{"type":"string"}},"required":["code","message"]},"description":"What keeps the domain's logo from showing, as far as DNS tells."}},"required":["status","name","record","logo_url","certificate_url","dmarc_policy","issues"],"description":"The result of the last BIMI check: whether mailbox providers can find the domain's brand logo and certificate. The record and the certificate are your own.","examples":[{"status":"configured","name":"default._bimi.acme.com","record":"v=BIMI1; l=https://acme.com/brand/logo.svg; a=https://acme.com/brand/vmc.pem","logo_url":"https://acme.com/brand/logo.svg","certificate_url":"https://acme.com/brand/vmc.pem","dmarc_policy":"reject","issues":[]}]},"CreateDomainRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The domain to send from, without a scheme or path. Subdomains are allowed; internationalized domains must be punycode-encoded.","examples":["acme.com"]},"subaccount":{"type":"string","minLength":1,"maxLength":256,"description":"Add it for one of your live sub-accounts (its id or your uid): only that sub-account sends from it, through its own reputation.","examples":["user_8812"]}},"required":["name"],"additionalProperties":false,"examples":[{"name":"acme.com"}]},"UpdateDomainRequest":{"type":"object","properties":{"shared_with_subaccounts":{"type":"boolean","description":"Let your sub-accounts send from this domain of yours (through your organization's reputation)."}},"required":["shared_with_subaccounts"],"additionalProperties":false,"examples":[{"shared_with_subaccounts":true}]},"DomainList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"domain","id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"acme.com","status":"verified","can_send":true,"region":"us-east-1","mail_from_domain":"send.acme.com","mail_from_status":"success","records":[{"priority":null,"required":true,"status":"verified","found":[],"purpose":"dkim","type":"CNAME","name":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e._domainkey.acme.com","value":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e.dkim.amazonses.com"},{"priority":10,"required":true,"status":"verified","found":[],"purpose":"mail_from_mx","type":"MX","name":"send.acme.com","value":"feedback-smtp.us-east-1.amazonses.com"},{"priority":null,"required":true,"status":"verified","found":[],"purpose":"mail_from_spf","type":"TXT","name":"send.acme.com","value":"v=spf1 include:amazonses.com ~all"},{"priority":null,"required":false,"status":"verified","found":[],"purpose":"dmarc","type":"TXT","name":"_dmarc.acme.com","value":"v=DMARC1; p=none;"}],"created_at":"2026-01-15T09:30:00.000Z","last_checked_at":"2026-01-15T09:42:10.000Z","verified_at":"2026-01-15T09:42:10.000Z","failed_at":null,"tracking":{"hostname":"links.acme.com","status":"active","record":{"type":"CNAME","name":"links.acme.com","value":"track.cosslinks.com","status":"verified","found":[]},"message":null,"created_at":"2026-01-15T09:45:00.000Z","last_checked_at":"2026-01-15T09:52:00.000Z","activated_at":"2026-01-15T09:52:00.000Z","failed_at":null},"receiving":null,"bimi":{"status":"configured","name":"default._bimi.acme.com","record":"v=BIMI1; l=https://acme.com/brand/logo.svg; a=https://acme.com/brand/vmc.pem","logo_url":"https://acme.com/brand/logo.svg","certificate_url":"https://acme.com/brand/vmc.pem","dmarc_policy":"reject","issues":[]},"subaccount_id":null,"shared_with_subaccounts":false}],"has_more":false}]},"DeletedDomain":{"type":"object","properties":{"object":{"type":"string","enum":["domain"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"domain","id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"CreateTrackingDomainRequest":{"type":"object","properties":{"hostname":{"type":"string","minLength":1,"maxLength":200,"description":"A subdomain of the domain to serve tracking links from, without a scheme or path. Point it at coss.com with the CNAME record the response lists.","examples":["links.acme.com"]}},"required":["hostname"],"additionalProperties":false,"examples":[{"hostname":"links.acme.com"}]},"CreateReceivingDomainRequest":{"type":"object","properties":{"hostname":{"type":"string","minLength":1,"maxLength":200,"description":"The domain itself or a subdomain of it, without a scheme or path. Point its MX at coss.com with the record the response lists. Using the domain itself moves all of its mail to coss.com, so a subdomain is usually the better choice.","examples":["inbound.acme.com"]}},"required":["hostname"],"additionalProperties":false,"examples":[{"hostname":"inbound.acme.com"}]},"DomainDmarc":{"type":"object","properties":{"object":{"type":"string","enum":["domain_dmarc"]},"domain_id":{"type":"string","description":"The domain's id."},"report_address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Where the domain's DMARC aggregate reports go (`rua=mailto:…`). `null` when this deployment doesn't receive email."},"record":{"anyOf":[{"$ref":"#/components/schemas/DmarcPublishedRecord"},{"type":"null"}]},"policy":{"anyOf":[{"type":"string","enum":["none","quarantine","reject"]},{"type":"null"}],"description":"The policy receivers apply: the record's `p` (`none` when it has none), or for a subdomain without a record of its own, its organizational domain's `sp` (else `p`)."},"inherited_from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The organizational domain whose DMARC record applies, when this domain publishes none of its own."},"policy_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When a DNS check first saw the current policy."},"stage":{"type":"string","enum":["not_checked","no_record","monitoring","quarantine","reject"],"description":"Where the domain is on the path to enforcement: `not_checked` (DNS not checked yet), `no_record`, `monitoring` (`p=none`), `quarantine` or `reject`."},"partial":{"type":"boolean","description":"The policy applies only partly (`pct` below 100, or `t=y`)."},"reporting":{"type":"boolean","description":"The published record sends aggregate reports to `report_address`."},"ready":{"type":"boolean","description":"Whether `next` is safe to publish now."},"next":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["publish","add_reporting","complete_rollout","tighten"],"description":"The kind of step this is."},"policy":{"type":"string","enum":["none","quarantine","reject"],"description":"The policy that step gets to."},"record":{"type":"string","description":"The TXT record to publish at `_dmarc.<domain>`."}},"required":["kind","policy","record"]},{"type":"null"}],"description":"The next step: `publish` a first record, `add_reporting` (send reports to coss.com), `complete_rollout` (drop `pct`/`t=y`) or `tighten` to the next policy. `null` at `p=reject`."},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["coverage","recent","complete","time_at_policy","coss_pass_rate","pass_rate","sources"],"description":"Which check this is."},"ok":{"type":"boolean","description":"Whether it passes."},"message":{"type":"string","description":"What it found."}},"required":["id","ok","message"]},"description":"The readiness checks gating `next`, from the last 14 days of reports."},"warnings":{"type":"array","items":{"type":"string"},"description":"Things to look at before tightening the policy."},"report_summary":{"type":"object","properties":{"period_start":{"type":"string","format":"date-time","description":"When the period starts."},"period_end":{"type":"string","format":"date-time","description":"When the period ends."},"reports":{"type":"integer","description":"Reports received."},"messages":{"type":"integer","description":"Messages they cover."},"passing":{"type":"integer","description":"Of those, how many passed DMARC."},"coss_messages":{"type":"integer","description":"Of those, how many were sent through coss.com."},"coss_passing":{"type":"integer","description":"Of those, how many passed DMARC."},"first_report_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When the first report arrived. `null`: none yet."},"last_report_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When the latest report arrived. `null`: none yet."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/DmarcSource"},"description":"The 50 sources with the most messages in the period."}},"required":["period_start","period_end","reports","messages","passing","coss_messages","coss_passing","first_report_at","last_report_at","sources"],"description":"What the aggregate reports of this period say."}},"required":["object","domain_id","report_address","record","policy","inherited_from","policy_since","stage","partial","reporting","ready","next","checks","warnings","report_summary"],"examples":[{"object":"domain_dmarc","domain_id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","report_address":"dmarc-k3x9m2pq7rtw4nbc@inbound.coss.com","record":{"value":"v=DMARC1; p=none; rua=mailto:dmarc-k3x9m2pq7rtw4nbc@inbound.coss.com;","p":"none","sp":null,"np":null,"adkim":null,"aspf":null,"pct":null,"t":null,"rua":["mailto:dmarc-k3x9m2pq7rtw4nbc@inbound.coss.com"]},"policy":"none","inherited_from":null,"policy_since":"2026-09-20T08:00:00.000Z","stage":"monitoring","partial":false,"reporting":true,"ready":true,"next":{"kind":"tighten","policy":"quarantine","record":"v=DMARC1; p=quarantine; rua=mailto:dmarc-k3x9m2pq7rtw4nbc@inbound.coss.com;"},"checks":[{"id":"coss_pass_rate","ok":true,"message":"100% of mail sent through coss.com passes DMARC (99% needed)."}],"warnings":[],"report_summary":{"period_start":"2026-09-26T00:00:00.000Z","period_end":"2026-10-10T00:00:00.000Z","reports":28,"messages":1846,"passing":1840,"coss_messages":1840,"coss_passing":1840,"first_report_at":"2026-09-21T00:00:00.000Z","last_report_at":"2026-10-09T23:59:59.000Z","sources":[{"source_ip":"54.240.8.12","header_from":"acme.com","messages":1840,"passing":1840,"via_coss":true}]}}]},"DmarcPublishedRecord":{"type":"object","properties":{"value":{"type":"string","description":"The `v=DMARC1` TXT record as published."},"p":{"anyOf":[{"type":"string","enum":["none","quarantine","reject"]},{"type":"null"}],"description":"The domain's policy tag."},"sp":{"anyOf":[{"type":"string","enum":["none","quarantine","reject"]},{"type":"null"}],"description":"The subdomain policy tag. `null`: not published."},"np":{"anyOf":[{"type":"string","enum":["none","quarantine","reject"]},{"type":"null"}],"description":"The policy tag for non-existent subdomains. `null`: not published."},"adkim":{"anyOf":[{"type":"string","enum":["r","s"]},{"type":"null"}],"description":"The DKIM alignment tag. `null`: not published."},"aspf":{"anyOf":[{"type":"string","enum":["r","s"]},{"type":"null"}],"description":"The SPF alignment tag. `null`: not published."},"pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Removed by RFC 9989 but still honored by many receivers."},"t":{"anyOf":[{"type":"string","enum":["y","n"]},{"type":"null"}],"description":"The testing tag. `null`: not published."},"rua":{"type":"array","items":{"type":"string"},"description":"Aggregate report addresses."}},"required":["value","p","sp","np","adkim","aspf","pct","t","rua"],"description":"The DMARC record found at `_dmarc.<domain>` by the latest DNS check.","examples":[{"value":"v=DMARC1; p=none; rua=mailto:dmarc-k3x9m2pq7rtw4nbc@inbound.coss.com;","p":"none","sp":null,"np":null,"adkim":null,"aspf":null,"pct":null,"t":null,"rua":["mailto:dmarc-k3x9m2pq7rtw4nbc@inbound.coss.com"]}]},"DmarcSource":{"type":"object","properties":{"source_ip":{"type":"string"},"header_from":{"type":"string","description":"The domain in the messages' From header."},"messages":{"type":"integer"},"passing":{"type":"integer","description":"Messages that passed DMARC."},"via_coss":{"type":"boolean","description":"Signed with the domain's coss.com DKIM keys or sent from its coss.com MAIL FROM domain."}},"required":["source_ip","header_from","messages","passing","via_coss"],"examples":[{"source_ip":"54.240.8.12","header_from":"acme.com","messages":1840,"passing":1840,"via_coss":true}]},"DmarcReportList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DmarcReportSummary"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"dmarc_report","id":"dmarcrep_01k7c8m4q2f3e9v6t5r1n0p8yz","domain_id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","reporter":{"org_name":"google.com","email":"noreply-dmarc-support@google.com"},"report_id":"13845021974128475","period_start":"2026-10-09T00:00:00.000Z","period_end":"2026-10-09T23:59:59.000Z","policy_published":{"domain":"acme.com","p":"none","sp":null,"np":null,"adkim":"r","aspf":"r","pct":100,"testing":null},"messages":1204,"passing":1200,"truncated":false,"received_at":"2026-10-10T03:12:44.000Z"}],"has_more":false}]},"DmarcReportSummary":{"type":"object","properties":{"object":{"type":"string","enum":["dmarc_report"]},"id":{"type":"string"},"domain_id":{"type":"string","description":"The domain's id."},"reporter":{"type":"object","properties":{"org_name":{"type":"string","description":"The reporting organization."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its contact address."}},"required":["org_name","email"],"description":"Who sent the report."},"report_id":{"type":"string","description":"The reporter's own id of the report."},"period_start":{"type":"string","format":"date-time","description":"When the period it covers starts."},"period_end":{"type":"string","format":"date-time","description":"When the period it covers ends."},"policy_published":{"type":"object","properties":{"domain":{"type":"string","description":"The domain the policy was published for."},"p":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The domain's policy tag."},"sp":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The subdomain policy tag."},"np":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The policy tag for non-existent subdomains."},"adkim":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The DKIM alignment tag."},"aspf":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The SPF alignment tag."},"pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The percentage tag."},"testing":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The testing tag."}},"required":["domain","p","sp","np","adkim","aspf","pct","testing"],"description":"The policy the reporter found when it evaluated the mail."},"messages":{"type":"integer","description":"Messages the report covers."},"passing":{"type":"integer","description":"Of those, how many passed DMARC."},"truncated":{"type":"boolean","description":"The report listed more rows than are kept (10,000); totals cover the kept rows."},"received_at":{"type":"string","format":"date-time","description":"When coss.com received it."}},"required":["object","id","domain_id","reporter","report_id","period_start","period_end","policy_published","messages","passing","truncated","received_at"],"examples":[{"object":"dmarc_report","id":"dmarcrep_01k7c8m4q2f3e9v6t5r1n0p8yz","domain_id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","reporter":{"org_name":"google.com","email":"noreply-dmarc-support@google.com"},"report_id":"13845021974128475","period_start":"2026-10-09T00:00:00.000Z","period_end":"2026-10-09T23:59:59.000Z","policy_published":{"domain":"acme.com","p":"none","sp":null,"np":null,"adkim":"r","aspf":"r","pct":100,"testing":null},"messages":1204,"passing":1200,"truncated":false,"received_at":"2026-10-10T03:12:44.000Z"}]},"DmarcReport":{"type":"object","properties":{"object":{"type":"string","enum":["dmarc_report"]},"id":{"type":"string"},"domain_id":{"type":"string","description":"The domain's id."},"reporter":{"type":"object","properties":{"org_name":{"type":"string","description":"The reporting organization."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its contact address."}},"required":["org_name","email"],"description":"Who sent the report."},"report_id":{"type":"string","description":"The reporter's own id of the report."},"period_start":{"type":"string","format":"date-time","description":"When the period it covers starts."},"period_end":{"type":"string","format":"date-time","description":"When the period it covers ends."},"policy_published":{"type":"object","properties":{"domain":{"type":"string","description":"The domain the policy was published for."},"p":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The domain's policy tag."},"sp":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The subdomain policy tag."},"np":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The policy tag for non-existent subdomains."},"adkim":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The DKIM alignment tag."},"aspf":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The SPF alignment tag."},"pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The percentage tag."},"testing":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The testing tag."}},"required":["domain","p","sp","np","adkim","aspf","pct","testing"],"description":"The policy the reporter found when it evaluated the mail."},"messages":{"type":"integer","description":"Messages the report covers."},"passing":{"type":"integer","description":"Of those, how many passed DMARC."},"truncated":{"type":"boolean","description":"The report listed more rows than are kept (10,000); totals cover the kept rows."},"received_at":{"type":"string","format":"date-time","description":"When coss.com received it."},"records":{"type":"array","items":{"$ref":"#/components/schemas/DmarcReportRecord"}}},"required":["object","id","domain_id","reporter","report_id","period_start","period_end","policy_published","messages","passing","truncated","received_at","records"],"examples":[{"object":"dmarc_report","id":"dmarcrep_01k7c8m4q2f3e9v6t5r1n0p8yz","domain_id":"dom_01k7c8m4q2f3e9v6t5r1n0p8yz","reporter":{"org_name":"google.com","email":"noreply-dmarc-support@google.com"},"report_id":"13845021974128475","period_start":"2026-10-09T00:00:00.000Z","period_end":"2026-10-09T23:59:59.000Z","policy_published":{"domain":"acme.com","p":"none","sp":null,"np":null,"adkim":"r","aspf":"r","pct":100,"testing":null},"messages":1204,"passing":1200,"truncated":false,"received_at":"2026-10-10T03:12:44.000Z","records":[{"source_ip":"54.240.8.12","count":1200,"disposition":"none","dkim":"pass","spf":"pass","dmarc_pass":true,"header_from":"acme.com","envelope_from":"send.acme.com","via_coss":true,"auth_results":{"dkim":[{"domain":"acme.com","selector":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e","result":"pass"}],"spf":[{"domain":"send.acme.com","scope":"mfrom","result":"pass"}]},"reasons":[]}]}]},"DmarcReportRecord":{"type":"object","properties":{"source_ip":{"type":"string","description":"The address the messages came from."},"count":{"type":"integer","description":"How many messages this line covers."},"disposition":{"type":"string","enum":["none","quarantine","reject"],"description":"What the receiver did with the messages."},"dkim":{"type":"string","enum":["pass","fail"],"description":"Aligned DKIM result."},"spf":{"type":"string","enum":["pass","fail"],"description":"Aligned SPF result."},"dmarc_pass":{"type":"boolean","description":"Whether they passed DMARC."},"header_from":{"type":"string","description":"The domain in their `From` header."},"envelope_from":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The domain in their envelope sender."},"via_coss":{"type":"boolean","description":"Whether they were sent through coss.com, by its DKIM selectors or bounce domain."},"auth_results":{"type":"object","properties":{"dkim":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"The signing domain."},"selector":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The selector."},"result":{"type":"string","description":"The result."}},"required":["domain","selector","result"]},"description":"Each DKIM signature's result."},"spf":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","description":"The checked domain."},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What it was checked against."},"result":{"type":"string","description":"The result."}},"required":["domain","scope","result"]},"description":"Each SPF check's result."}},"required":["dkim","spf"],"description":"What receivers saw for DKIM and SPF."},"reasons":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"The kind of override."},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The receiver's comment."}},"required":["type","comment"]},"description":"Why receivers overrode the policy."}},"required":["source_ip","count","disposition","dkim","spf","dmarc_pass","header_from","envelope_from","via_coss","auth_results","reasons"],"examples":[{"source_ip":"54.240.8.12","count":1200,"disposition":"none","dkim":"pass","spf":"pass","dmarc_pass":true,"header_from":"acme.com","envelope_from":"send.acme.com","via_coss":true,"auth_results":{"dkim":[{"domain":"acme.com","selector":"x7f3k2m9qp4ld8sv6hwz1nyc5rbtgj0e","result":"pass"}],"spf":[{"domain":"send.acme.com","scope":"mfrom","result":"pass"}]},"reasons":[]}]},"DedicatedIpPool":{"type":"object","properties":{"object":{"type":"string","enum":["dedicated_ip_pool"]},"status":{"type":"string","enum":["not_enabled","waiting","provisioning","warming","ready","releasing"],"description":"`not_enabled` without the Dedicated IPs add-on. `provisioning` while the pool is set up (`waiting` when none is free yet), then `warming`: live emails go through the pool while it warms up its IPs, sending what they can't take yet from shared IPs. `ready` once at least 95% of the last 7 days' deliveries (at least 1,000) left from your dedicated IPs. `releasing` after the add-on ends: emails are back on shared IPs, and the pool is released a day later."},"ips":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string","description":"An IPv4 address of the pool."},"delivered_7d":{"type":"integer","description":"Deliveries from it in the last 7 days."}},"required":["ip","delivered_7d"]},"description":"The pool's IPs; the provider adds and removes them with volume."},"dedicated_share":{"type":["number","null"],"description":"Share (0–1) of the last 7 days' deliveries that left from the pool's IPs (`null`: fewer than 1,000)."},"message":{"type":["string","null"],"description":"What is holding the pool up, if anything."},"created_at":{"type":["string","null"],"format":"date-time"},"ready_at":{"type":["string","null"],"format":"date-time","description":"When it was first `ready`."}},"required":["object","status","ips","dedicated_share","message","created_at","ready_at"],"description":"Your organization's dedicated IPs (the Dedicated IPs add-on): a pool managed and warmed up automatically.","examples":[{"object":"dedicated_ip_pool","status":"warming","ips":[{"ip":"198.51.100.10","delivered_7d":18420}],"dedicated_share":0.72,"message":null,"created_at":"2026-10-12T09:31:00.000Z","ready_at":null}]},"WebhookEndpointWithSecret":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_endpoint"]},"id":{"type":"string","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","description":"Where events are posted.","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"],"description":"Your note about it. `null`: none."},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`.","examples":["2026-10-10"]},"enabled":{"type":"boolean","description":"A disabled endpoint receives nothing until it is enabled again."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: someone disabled it. `failing`: its deliveries failed every attempt for five days, so coss.com disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When it was disabled. `null` while enabled."},"failing_since":{"type":["string","null"],"format":"date-time","description":"When the endpoint's current run of failed deliveries began (a delivery that failed every attempt); cleared by the next successful delivery. An endpoint failing for five days is disabled. `null` while healthy."},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"After a secret roll, deliveries are also signed with the previous secret until this time. `null` when only the current secret signs."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"The endpoint's `whsec_…` signing secret, used to verify the requests coss.com sends. Returned only when the endpoint is created and when its secret is rolled — store it now; it cannot be read back through the API.","examples":["whsec_6Jk…"]}},"required":["object","id","url","description","event_types","api_version","enabled","disabled_reason","disabled_at","failing_since","previous_secret_expires_at","created_at","updated_at","secret"],"examples":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.delivered","email.bounced"],"api_version":"2026-10-10","enabled":true,"disabled_reason":null,"disabled_at":null,"failing_since":null,"previous_secret_expires_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","secret":"whsec_6Jk…"}]},"CreateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL coss.com posts events to.","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"event_types":{"type":"array","items":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","email.unsubscribed","email.received","domain.dmarc_report_received","account.reputation_warning","account.reputation_recovered","account.suspended","account.reinstated","account.marketing_paused","account.marketing_reinstated","subaccount.reputation_warning","subaccount.reputation_recovered","subaccount.paused","subaccount.reinstated","hook_endpoint.disabled","billing.invoice_finalized","billing.invoice_paid","billing.invoice_payment_failed","billing.invoice_voided","billing.plan_changed","billing.usage_threshold_reached","billing.hold_placed","billing.hold_lifted","billing.credit_granted","billing.budget_threshold_reached","billing.budget_hold_placed","billing.budget_hold_lifted","risk.assessment.review","risk.assessment.reviewed","contact.created","contact.updated","contact.deleted","contact.unsubscribed","contact.confirmed","broadcast.sending","broadcast.sent","broadcast.paused","broadcast.canceled","broadcast.failed","inbox.message.received","sms.scheduled","sms.sent","sms.delivered","sms.undelivered","sms.failed","sms.suppressed","sms.canceled","sms.received","sms.opted_out","sms.opted_in","sign_request.sent","sign_request.viewed","sign_request.signer_signed","sign_request.declined","sign_request.completed","sign_request.canceled","sign_request.expired","verification.approved","verification.failed","verification.blocked","form.submission.received","form.submission.flagged","scheduling.booking.created","scheduling.booking.pending_approval","scheduling.booking.confirmed","scheduling.booking.rescheduled","scheduling.booking.cancelled","scheduling.booking.declined","scheduling.booking.no_show","scheduling.booking.external_conflict","scheduling.booking.calendar_write_failed","scheduling.booking.location_ready","scheduling.booking.reassigned","scheduling.booking.started","scheduling.booking.ended","scheduling.booking.reminder","scheduling.calendar.connected","scheduling.calendar.needs_reauth","scheduling.calendar.disconnected","scheduling.calendar_delegation.failing","scheduling.calendar_delegation.restored","scheduling.out_of_office.created","scheduling.out_of_office.updated","scheduling.out_of_office.deleted","scheduling.out_of_office.started","scheduling.out_of_office.ended","scheduling.reassignment.completed","scheduling.oauth_app.failing","scheduling.oauth_app.restored"]},"maxItems":100,"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later. Defaults to every event type."},"api_version":{"type":"string","enum":["2026-10-10"],"description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`. Defaults to the version of the request that creates the endpoint."}},"required":["url"],"additionalProperties":false,"examples":[{"url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.sent","email.delivered"]}]},"WebhookEndpointList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.delivered","email.bounced"],"api_version":"2026-10-10","enabled":true,"disabled_reason":null,"disabled_at":null,"failing_since":null,"previous_secret_expires_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"WebhookEndpoint":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_endpoint"]},"id":{"type":"string","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","description":"Where events are posted.","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"],"description":"Your note about it. `null`: none."},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later."},"api_version":{"type":"string","description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`.","examples":["2026-10-10"]},"enabled":{"type":"boolean","description":"A disabled endpoint receives nothing until it is enabled again."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: someone disabled it. `failing`: its deliveries failed every attempt for five days, so coss.com disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When it was disabled. `null` while enabled."},"failing_since":{"type":["string","null"],"format":"date-time","description":"When the endpoint's current run of failed deliveries began (a delivery that failed every attempt); cleared by the next successful delivery. An endpoint failing for five days is disabled. `null` while healthy."},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"After a secret roll, deliveries are also signed with the previous secret until this time. `null` when only the current secret signs."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","url","description","event_types","api_version","enabled","disabled_reason","disabled_at","failing_since","previous_secret_expires_at","created_at","updated_at"],"examples":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks/coss","description":"Production receiver","event_types":["email.delivered","email.bounced"],"api_version":"2026-10-10","enabled":true,"disabled_reason":null,"disabled_at":null,"failing_since":null,"previous_secret_expires_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"UpdateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL coss.com posts events to.","examples":["https://example.com/webhooks/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"event_types":{"type":"array","items":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","email.unsubscribed","email.received","domain.dmarc_report_received","account.reputation_warning","account.reputation_recovered","account.suspended","account.reinstated","account.marketing_paused","account.marketing_reinstated","subaccount.reputation_warning","subaccount.reputation_recovered","subaccount.paused","subaccount.reinstated","hook_endpoint.disabled","billing.invoice_finalized","billing.invoice_paid","billing.invoice_payment_failed","billing.invoice_voided","billing.plan_changed","billing.usage_threshold_reached","billing.hold_placed","billing.hold_lifted","billing.credit_granted","billing.budget_threshold_reached","billing.budget_hold_placed","billing.budget_hold_lifted","risk.assessment.review","risk.assessment.reviewed","contact.created","contact.updated","contact.deleted","contact.unsubscribed","contact.confirmed","broadcast.sending","broadcast.sent","broadcast.paused","broadcast.canceled","broadcast.failed","inbox.message.received","sms.scheduled","sms.sent","sms.delivered","sms.undelivered","sms.failed","sms.suppressed","sms.canceled","sms.received","sms.opted_out","sms.opted_in","sign_request.sent","sign_request.viewed","sign_request.signer_signed","sign_request.declined","sign_request.completed","sign_request.canceled","sign_request.expired","verification.approved","verification.failed","verification.blocked","form.submission.received","form.submission.flagged","scheduling.booking.created","scheduling.booking.pending_approval","scheduling.booking.confirmed","scheduling.booking.rescheduled","scheduling.booking.cancelled","scheduling.booking.declined","scheduling.booking.no_show","scheduling.booking.external_conflict","scheduling.booking.calendar_write_failed","scheduling.booking.location_ready","scheduling.booking.reassigned","scheduling.booking.started","scheduling.booking.ended","scheduling.booking.reminder","scheduling.calendar.connected","scheduling.calendar.needs_reauth","scheduling.calendar.disconnected","scheduling.calendar_delegation.failing","scheduling.calendar_delegation.restored","scheduling.out_of_office.created","scheduling.out_of_office.updated","scheduling.out_of_office.deleted","scheduling.out_of_office.started","scheduling.out_of_office.ended","scheduling.reassignment.completed","scheduling.oauth_app.failing","scheduling.oauth_app.restored"]},"maxItems":100,"description":"Event types delivered to this endpoint. An empty array means every event type, including ones added later."},"api_version":{"type":"string","enum":["2026-10-10"],"description":"The API version (`Coss-Version`) events are rendered in for this endpoint. Each event carries it as `api_version`."},"enabled":{"type":"boolean"}},"additionalProperties":false,"examples":[{"enabled":false}]},"RollWebhookEndpointSecretRequest":{"type":"object","properties":{"previous_secret_expires_in":{"type":"integer","minimum":0,"maximum":604800,"description":"Seconds the current secret keeps signing deliveries next to the new one, so receivers can switch without rejecting anything. Default 86400 (a day), at most 604800 (a week). `0` stops it immediately, e.g. after a leak."}},"additionalProperties":false,"examples":[{"previous_secret_expires_in":3600}]},"DeletedWebhookEndpoint":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_endpoint"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"webhook_endpoint","id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"WebhookEndpointRecovery":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_endpoint_recovery"]},"endpoint_id":{"type":"string","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"requeued":{"type":"integer","description":"How many failed deliveries were queued for one more attempt. Their attempts are spread over the next minute."},"has_more":{"type":"boolean","description":"At most 1,000 are requeued per call; `true` means call again with the same `since`."}},"required":["object","endpoint_id","requeued","has_more"],"examples":[{"object":"webhook_endpoint_recovery","endpoint_id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","requeued":12,"has_more":false}]},"RecoverWebhookEndpointRequest":{"type":"object","properties":{"since":{"type":"string","format":"date-time","description":"Requeue the endpoint's deliveries that failed and were created at or after this time (ISO 8601). Deliveries are kept for 30 days.","examples":["2026-01-15T09:00:00.000Z"]}},"required":["since"],"additionalProperties":false,"examples":[{"since":"2026-01-15T09:00:00.000Z"}]},"WebhookDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"webhook_delivery","id":"whdel_01k7c8n2b5d7f9h1k3m5p7r9tv","endpoint_id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","event_id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","event_type":"email.delivered","status":"succeeded","attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"payload":{"id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","object":"event","type":"email.delivered","created_at":"2026-01-15T09:30:00.000Z","data":{"email_id":"email_01k7c8m9x3a5c7e9g1j3l5n7q9","recipient":"user@example.com"}},"attempts":[{"object":"webhook_attempt","id":"whatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}],"has_more":false}]},"WebhookDelivery":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_delivery"]},"id":{"type":"string","examples":["whdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"endpoint_id":{"type":"string","description":"The id of the endpoint it's delivered to."},"event_id":{"type":"string","description":"The event's id: the `id` of the payload and the `webhook-id` header."},"event_type":{"type":"string","examples":["email.delivered"]},"status":{"$ref":"#/components/schemas/WebhookDeliveryStatus"},"attempt_count":{"type":"integer","description":"How many attempts were made so far."},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"When the next attempt is due; `null` once the delivery is finished."},"last_status_code":{"type":["integer","null"],"description":"The endpoint's HTTP status on the latest attempt. `null`: no response arrived, or no attempt yet."},"last_error":{"type":["string","null"],"description":"Why the latest attempt failed. `null`: it didn't, or no attempt yet."},"payload":{"type":"object","additionalProperties":{},"description":"The event body, exactly as posted to the endpoint."},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/WebhookAttempt"},"description":"Every HTTP attempt of this delivery, oldest first."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","endpoint_id","event_id","event_type","status","attempt_count","next_attempt_at","last_status_code","last_error","payload","attempts","created_at","updated_at"],"examples":[{"object":"webhook_delivery","id":"whdel_01k7c8n2b5d7f9h1k3m5p7r9tv","endpoint_id":"whep_01k7c8m4q2f3e9v6t5r1n0p8yz","event_id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","event_type":"email.delivered","status":"succeeded","attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"payload":{"id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","object":"event","type":"email.delivered","created_at":"2026-01-15T09:30:00.000Z","data":{"email_id":"email_01k7c8m9x3a5c7e9g1j3l5n7q9","recipient":"user@example.com"}},"attempts":[{"object":"webhook_attempt","id":"whatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}]},"WebhookDeliveryStatus":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending`: waiting for its next attempt. `succeeded`: the endpoint answered with a 2xx status. `failed`: every attempt failed, or the endpoint was disabled."},"WebhookAttempt":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_attempt"]},"id":{"type":"string"},"attempted_at":{"type":"string","format":"date-time","description":"When the attempt ran."},"status_code":{"type":["integer","null"],"description":"The endpoint's HTTP status; `null` when no response arrived."},"duration_ms":{"type":"integer","description":"How long it took, in milliseconds."},"error":{"type":["string","null"],"description":"Why the attempt failed (e.g. `HTTP 500`, a timeout); `null` on success."},"response_excerpt":{"type":["string","null"],"description":"At most 1 KB of the response body, as text."}},"required":["object","id","attempted_at","status_code","duration_ms","error","response_excerpt"],"examples":[{"object":"webhook_attempt","id":"whatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}]},"WebhookListener":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_listener"]},"id":{"type":"string","examples":["whlis_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"api_version":{"type":"string","description":"The API version (`Coss-Version`) the listener's events are rendered in.","examples":["2026-10-10"]},"event_types":{"type":"array","items":{"type":"string"},"description":"Event types the listener receives. An empty array means every event type."},"description":{"type":["string","null"],"description":"Your note about it, such as the machine it's on. `null`: none."},"expires_at":{"type":"string","format":"date-time","description":"When the listener closes unless it is polled again; every poll moves it 10 minutes ahead."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","api_version","event_types","description","expires_at","created_at"],"examples":[{"object":"webhook_listener","id":"whlis_01k7c8m4q2f3e9v6t5r1n0p8yz","api_version":"2026-10-10","event_types":["email.delivered","email.bounced"],"description":"bailey-mbp → localhost:3000/webhooks","expires_at":"2026-01-15T09:40:00.000Z","created_at":"2026-01-15T09:30:00.000Z"}]},"CreateWebhookListenerRequest":{"type":"object","properties":{"event_types":{"type":"array","items":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","email.unsubscribed","email.received","domain.dmarc_report_received","account.reputation_warning","account.reputation_recovered","account.suspended","account.reinstated","account.marketing_paused","account.marketing_reinstated","subaccount.reputation_warning","subaccount.reputation_recovered","subaccount.paused","subaccount.reinstated","hook_endpoint.disabled","billing.invoice_finalized","billing.invoice_paid","billing.invoice_payment_failed","billing.invoice_voided","billing.plan_changed","billing.usage_threshold_reached","billing.hold_placed","billing.hold_lifted","billing.credit_granted","billing.budget_threshold_reached","billing.budget_hold_placed","billing.budget_hold_lifted","risk.assessment.review","risk.assessment.reviewed","contact.created","contact.updated","contact.deleted","contact.unsubscribed","contact.confirmed","broadcast.sending","broadcast.sent","broadcast.paused","broadcast.canceled","broadcast.failed","inbox.message.received","sms.scheduled","sms.sent","sms.delivered","sms.undelivered","sms.failed","sms.suppressed","sms.canceled","sms.received","sms.opted_out","sms.opted_in","sign_request.sent","sign_request.viewed","sign_request.signer_signed","sign_request.declined","sign_request.completed","sign_request.canceled","sign_request.expired","verification.approved","verification.failed","verification.blocked","form.submission.received","form.submission.flagged","scheduling.booking.created","scheduling.booking.pending_approval","scheduling.booking.confirmed","scheduling.booking.rescheduled","scheduling.booking.cancelled","scheduling.booking.declined","scheduling.booking.no_show","scheduling.booking.external_conflict","scheduling.booking.calendar_write_failed","scheduling.booking.location_ready","scheduling.booking.reassigned","scheduling.booking.started","scheduling.booking.ended","scheduling.booking.reminder","scheduling.calendar.connected","scheduling.calendar.needs_reauth","scheduling.calendar.disconnected","scheduling.calendar_delegation.failing","scheduling.calendar_delegation.restored","scheduling.out_of_office.created","scheduling.out_of_office.updated","scheduling.out_of_office.deleted","scheduling.out_of_office.started","scheduling.out_of_office.ended","scheduling.reassignment.completed","scheduling.oauth_app.failing","scheduling.oauth_app.restored"]},"maxItems":100,"description":"Event types to receive. Defaults to every event type."},"api_version":{"type":"string","enum":["2026-10-10"],"description":"The API version events are rendered in. Defaults to the version of the request that creates the listener."},"description":{"type":["string","null"],"maxLength":256,"description":"Where the events go, for your own reference (shown in the log)."}},"additionalProperties":false,"examples":[{"event_types":["email.sent","email.delivered"],"description":"localhost:3000/webhooks"}]},"WebhookListenerPoll":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_listener_poll"]},"listener":{"$ref":"#/components/schemas/WebhookListener"},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookListenerDelivery"},"description":"Events to forward, oldest first. Empty when none arrived while the poll waited. A delivery not acknowledged within two minutes is handed out again."},"acknowledged":{"type":"integer","description":"How many of the request's acknowledgements were recorded."}},"required":["object","listener","deliveries","acknowledged"],"examples":[{"object":"webhook_listener_poll","listener":{"object":"webhook_listener","id":"whlis_01k7c8m4q2f3e9v6t5r1n0p8yz","api_version":"2026-10-10","event_types":["email.delivered","email.bounced"],"description":"bailey-mbp → localhost:3000/webhooks","expires_at":"2026-01-15T09:40:00.000Z","created_at":"2026-01-15T09:30:00.000Z"},"deliveries":[{"object":"webhook_listener_delivery","id":"whlisdel_01k7c8n2b5d7f9h1k3m5p7r9tv","ack_token":"mfz3k2a8","event_id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","event_type":"email.delivered","attempt":1,"body":"{\"id\":\"evt_01k7c8n1z4c6e8g0j2l4n6q8sa\",\"object\":\"event\",\"type\":\"email.delivered\",\"api_version\":\"2026-10-10\",\"created_at\":\"2026-01-15T09:30:00.000Z\",\"data\":{\"email_id\":\"email_01k7c8m9x3a5c7e9g1j3l5n7q9\",\"recipient\":\"user@example.com\"}}","created_at":"2026-01-15T09:30:00.000Z"}],"acknowledged":0}]},"WebhookListenerDelivery":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_listener_delivery"]},"id":{"type":"string","examples":["whlisdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"ack_token":{"type":"string","description":"Send it back with the delivery's acknowledgement in a later poll."},"event_id":{"type":"string","description":"The event's id: the `id` of the body, and the `webhook-id` header endpoints receive."},"event_type":{"type":"string","examples":["email.delivered"]},"attempt":{"type":"integer","description":"How many polls have handed it out: more than 1 when an earlier answer was never acknowledged."},"body":{"type":"string","description":"The event body, exactly as an endpoint with the listener's API version would receive it."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","ack_token","event_id","event_type","attempt","body","created_at"],"examples":[{"object":"webhook_listener_delivery","id":"whlisdel_01k7c8n2b5d7f9h1k3m5p7r9tv","ack_token":"mfz3k2a8","event_id":"evt_01k7c8n1z4c6e8g0j2l4n6q8sa","event_type":"email.delivered","attempt":1,"body":"{\"id\":\"evt_01k7c8n1z4c6e8g0j2l4n6q8sa\",\"object\":\"event\",\"type\":\"email.delivered\",\"api_version\":\"2026-10-10\",\"created_at\":\"2026-01-15T09:30:00.000Z\",\"data\":{\"email_id\":\"email_01k7c8m9x3a5c7e9g1j3l5n7q9\",\"recipient\":\"user@example.com\"}}","created_at":"2026-01-15T09:30:00.000Z"}]},"PollWebhookListenerRequest":{"type":"object","properties":{"acks":{"type":"array","items":{"$ref":"#/components/schemas/WebhookListenerAck"},"maxItems":50,"description":"What happened to deliveries handed out earlier. A delivery is finished once acknowledged: a 2xx status (or none, with no error) succeeds; anything else fails. Neither is retried."},"wait_ms":{"type":"integer","minimum":0,"maximum":25000,"description":"How long to wait for deliveries when none is pending, in milliseconds. Default 20000, at most 25000."},"limit":{"type":"integer","minimum":1,"maximum":50,"description":"The most deliveries to hand out. Default 10, at most 50."}},"additionalProperties":false,"examples":[{"acks":[{"delivery_id":"whlisdel_01k7c8n2b5d7f9h1k3m5p7r9tv","ack_token":"mfz3k2a8","status_code":200,"duration_ms":12,"error":null}],"wait_ms":20000}]},"WebhookListenerAck":{"type":"object","properties":{"delivery_id":{"type":"string","examples":["whlisdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"ack_token":{"type":"string","maxLength":64,"description":"The delivery's `ack_token`."},"status_code":{"type":["integer","null"],"minimum":100,"maximum":599,"description":"What the local URL answered; `null` when nothing answered, or when the event was only printed."},"duration_ms":{"type":"integer","minimum":0,"maximum":3600000},"error":{"type":["string","null"],"maxLength":500,"description":"Why forwarding failed (e.g. `connection refused`); `null` if it didn't."}},"required":["delivery_id","ack_token","status_code","duration_ms","error"],"additionalProperties":false},"DeletedWebhookListener":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_listener"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"webhook_listener","id":"whlis_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"WebhookTestEvent":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_test_event"]},"event":{"anyOf":[{"$ref":"#/components/schemas/EmailWebhookEvent"},{"$ref":"#/components/schemas/ReceivedEmailWebhookEvent"},{"$ref":"#/components/schemas/HookEndpointWebhookEvent"},{"$ref":"#/components/schemas/RiskWebhookEvent"},{"$ref":"#/components/schemas/ContactWebhookEvent"},{"$ref":"#/components/schemas/BroadcastWebhookEvent"},{"$ref":"#/components/schemas/InboxMessageReceivedWebhookEvent"},{"$ref":"#/components/schemas/SmsWebhookEvent"},{"$ref":"#/components/schemas/ReceivedSmsWebhookEvent"},{"$ref":"#/components/schemas/SignRequestWebhookEvent"},{"$ref":"#/components/schemas/VerificationWebhookEvent"},{"$ref":"#/components/schemas/FormSubmissionWebhookEvent"},{"$ref":"#/components/schemas/SchedulingBookingWebhookEvent"},{"$ref":"#/components/schemas/SchedulingCalendarWebhookEvent"},{"$ref":"#/components/schemas/SchedulingCalendarDelegationWebhookEvent"},{"$ref":"#/components/schemas/SchedulingOutOfOfficeWebhookEvent"},{"$ref":"#/components/schemas/SchedulingReassignmentWebhookEvent"},{"$ref":"#/components/schemas/SchedulingCalendarDelegationWebhookEvent"},{"$ref":"#/components/schemas/SchedulingOauthAppWebhookEvent"}],"description":"The event, as an endpoint on the request's API version receives it. Its `webhook-id` header is `event.id`."},"endpoints":{"type":"integer","description":"Enabled endpoints of the environment subscribed to the type, each sent it once."},"listeners":{"type":"integer","description":"Open `coss listen` listeners subscribed to the type, each handed it once."}},"required":["object","event","endpoints","listeners"],"examples":[{"object":"webhook_test_event","event":{"id":"evt_01k7c8m4r0c2b8w9y3d5f6g7h8","object":"event","type":"email.bounced","api_version":"2026-10-10","created_at":"2026-10-10T12:00:03.000Z","data":{"email_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Acme <onboarding@acme.com>","to":["ada@example.com"],"subject":"Welcome to Acme","tags":[{"name":"template","value":"welcome"}],"category":"onboarding","sandbox":true,"recipient":"ada@example.com","occurred_at":"2026-10-10T12:00:03.000Z","bounce":{"type":"permanent","sub_type":"General","diagnostic_code":"smtp; 550 5.1.1 The email account that you tried to reach does not exist"}}},"endpoints":1,"listeners":1}]},"InboxMessageReceivedWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, and the `webhook-id` header."},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["inbox.message.received"]},"api_version":{"type":"string","description":"The API version (`Coss-Version`) this event is rendered in: the receiving endpoint's `api_version`.","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"inbox_id":{"type":"string"},"inbox_address":{"type":"string"},"thread_id":{"type":"string"},"message_id":{"type":"string","description":"The inbox message's id (`imsg_…`)."},"received_email_id":{"type":"string"},"from":{"type":["string","null"]},"to":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"attachment_count":{"type":"integer"},"new_thread":{"type":"boolean","description":"Whether the message started its thread."},"spam":{"type":"boolean"},"sandbox":{"type":"boolean"},"received_at":{"type":"string","format":"date-time"}},"required":["inbox_id","inbox_address","thread_id","message_id","received_email_id","from","to","subject","attachment_count","new_thread","spam","sandbox","received_at"]}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k7c8m4r0c2b8w9y3d5f6g7j1","object":"event","type":"inbox.message.received","api_version":"2026-10-10","created_at":"2026-10-10T12:00:01.000Z","data":{"inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","inbox_address":"support-agent@k3j9x2m7qp4l.inbound.coss.com","thread_id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","message_id":"imsg_01k7c8m4s1d3c9x0z4e6g7h8j9","received_email_id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"Jane Doe <jane@example.com>","to":["support-agent@k3j9x2m7qp4l.inbound.coss.com"],"subject":"My order arrived damaged","attachment_count":1,"new_thread":true,"spam":false,"sandbox":false,"received_at":"2026-10-10T12:00:00.000Z"}}]},"VerificationWebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["event"]},"type":{"type":"string","enum":["verification.approved","verification.failed","verification.blocked"],"description":"What happened to the verification."},"api_version":{"type":"string","description":"The API version the payload is rendered in (your endpoint's version).","examples":["2026-10-10"]},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"data":{"type":"object","properties":{"verification_id":{"type":"string","description":"The verification's id."},"channel":{"type":"string","enum":["sms","email"],"description":"`sms` or `email`."},"to":{"type":"string","description":"The phone number (E.164) or address the code goes to."},"status":{"type":"string","enum":["pending","approved","expired","canceled","failed","blocked"],"description":"Its status after this event."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"],"description":"Why it `failed`. `null` otherwise."},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"value":{"type":"number"}},"required":["code"],"description":"A fraud guard reason (see the docs' list)."},"description":"Why it was `blocked`. Empty otherwise."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The tag's name."},"value":{"type":"string","description":"The tag's value."}},"required":["name","value"]},"description":"Your tags on the verification."},"sandbox":{"type":"boolean","description":"Whether it's made in a sandbox environment: simulated."},"occurred_at":{"type":"string","format":"date-time","description":"When this happened."}},"required":["verification_id","channel","to","status","failure","reasons","tags","sandbox","occurred_at"],"description":"The verification. Never its code."}},"required":["id","object","type","api_version","created_at","data"],"examples":[{"id":"evt_01k8e2m4q2f3e9v6t5r1n0p8yz","object":"event","type":"verification.approved","api_version":"2026-10-10","created_at":"2026-11-10T12:00:41.100Z","data":{"verification_id":"vrf_01k8e2m4q2f3e9v6t5r1n0p8yz","channel":"sms","to":"+14155550199","status":"approved","failure":null,"reasons":[],"tags":[],"sandbox":false,"occurred_at":"2026-11-10T12:00:41.000Z"}}]},"CreateTestWebhookEventRequest":{"type":"object","properties":{"type":{"type":"string","enum":["email.sent","email.delivered","email.delivery_delayed","email.bounced","email.complained","email.failed","email.suppressed","email.scheduled","email.canceled","email.opened","email.clicked","email.rescheduled","email.unsubscribed","email.received","domain.dmarc_report_received","account.reputation_warning","account.reputation_recovered","account.suspended","account.reinstated","account.marketing_paused","account.marketing_reinstated","subaccount.reputation_warning","subaccount.reputation_recovered","subaccount.paused","subaccount.reinstated","hook_endpoint.disabled","billing.invoice_finalized","billing.invoice_paid","billing.invoice_payment_failed","billing.invoice_voided","billing.plan_changed","billing.usage_threshold_reached","billing.hold_placed","billing.hold_lifted","billing.credit_granted","billing.budget_threshold_reached","billing.budget_hold_placed","billing.budget_hold_lifted","risk.assessment.review","risk.assessment.reviewed","contact.created","contact.updated","contact.deleted","contact.unsubscribed","contact.confirmed","broadcast.sending","broadcast.sent","broadcast.paused","broadcast.canceled","broadcast.failed","inbox.message.received","sms.scheduled","sms.sent","sms.delivered","sms.undelivered","sms.failed","sms.suppressed","sms.canceled","sms.received","sms.opted_out","sms.opted_in","sign_request.sent","sign_request.viewed","sign_request.signer_signed","sign_request.declined","sign_request.completed","sign_request.canceled","sign_request.expired","verification.approved","verification.failed","verification.blocked","form.submission.received","form.submission.flagged","scheduling.booking.created","scheduling.booking.pending_approval","scheduling.booking.confirmed","scheduling.booking.rescheduled","scheduling.booking.cancelled","scheduling.booking.declined","scheduling.booking.no_show","scheduling.booking.external_conflict","scheduling.booking.calendar_write_failed","scheduling.booking.location_ready","scheduling.booking.reassigned","scheduling.booking.started","scheduling.booking.ended","scheduling.booking.reminder","scheduling.calendar.connected","scheduling.calendar.needs_reauth","scheduling.calendar.disconnected","scheduling.calendar_delegation.failing","scheduling.calendar_delegation.restored","scheduling.out_of_office.created","scheduling.out_of_office.updated","scheduling.out_of_office.deleted","scheduling.out_of_office.started","scheduling.out_of_office.ended","scheduling.reassignment.completed","scheduling.oauth_app.failing","scheduling.oauth_app.restored"],"description":"The event type. `domain.*`, `account.*`, `subaccount.*` and `billing.*` events only reach live environments, so they can't be tested in a sandbox one."},"data":{"type":"object","additionalProperties":{},"description":"Fields merged over the sample's `data` (objects field by field, anything else replaced), in the latest API version's shape: e.g. a real `email_id`, or the `recipient` your handler looks for. Unknown fields are refused."}},"required":["type"],"additionalProperties":false,"examples":[{"type":"email.bounced","data":{"recipient":"ada@example.com"}}]},"Suppression":{"type":"object","properties":{"object":{"type":"string","enum":["suppression"]},"id":{"type":"string","examples":["sup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"address":{"type":"string","description":"The bare, lower-cased address."},"scope":{"type":"string","description":"`*` (every email) or a category."},"reason":{"type":"string","enum":["bounce","complaint","manual","import","unsubscribe"],"description":"`bounce`: added after a permanent bounce. `complaint`: added after a spam complaint. `manual`: added one by one through the API or dashboard. `import`: added by a bulk import. `unsubscribe`: added by the recipient's one-click unsubscribe, scoped to the email's category."},"email_id":{"type":["string","null"],"description":"The email whose bounce or complaint added this entry."},"subaccount_id":{"type":["string","null"],"description":"The sub-account whose list it is on; `null` for the environment's own list."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","address","scope","reason","email_id","subaccount_id","created_at"],"examples":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"user@example.com","scope":"marketing","reason":"manual","email_id":null,"subaccount_id":null,"created_at":"2026-01-15T09:30:00.000Z"}]},"CreateSuppressionRequest":{"type":"object","properties":{"address":{"type":"string","description":"The address to suppress. Display names are ignored; matching is case-insensitive."},"scope":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","enum":["stream:marketing"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}],"description":"Defaults to `*` (every email). Pass a category, e.g. \"marketing\", to only skip those."},"subaccount":{"type":"string","minLength":1,"maxLength":256,"description":"Add it to a sub-account's own list (its id or your uid) instead of the environment's.","examples":["user_8812"]}},"required":["address"],"additionalProperties":false,"examples":[{"address":"user@example.com","scope":"marketing"}]},"SuppressionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Suppression"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"user@example.com","scope":"marketing","reason":"manual","email_id":null,"subaccount_id":null,"created_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"SuppressionCheck":{"type":"object","properties":{"object":{"type":"string","enum":["suppression_check"]},"address":{"type":"string","description":"The address checked."},"suppressed":{"type":"boolean","description":"Whether a send (with the given category) would skip this address."},"suppressions":{"type":"array","items":{"$ref":"#/components/schemas/Suppression"},"description":"The entries that match."}},"required":["object","address","suppressed","suppressions"],"examples":[{"object":"suppression_check","address":"user@example.com","suppressed":true,"suppressions":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"user@example.com","scope":"marketing","reason":"manual","email_id":null,"subaccount_id":null,"created_at":"2026-01-15T09:30:00.000Z"}]}]},"SuppressionImport":{"type":"object","properties":{"object":{"type":"string","enum":["suppression_import"]},"created":{"type":"integer","description":"Entries added by this import."},"existing":{"type":"integer","description":"Valid entries that were already on the list (or repeated within this import); unchanged."},"invalid":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Position of the entry in the request."},"address":{"type":"string"},"message":{"type":"string"}},"required":["index","address","message"]},"description":"Entries that were skipped, with the reason."}},"required":["object","created","existing","invalid"],"examples":[{"object":"suppression_import","created":2,"existing":0,"invalid":[]}]},"ImportSuppressionsRequest":{"type":"object","properties":{"subaccount":{"type":"string","minLength":1,"maxLength":256,"description":"Import into a sub-account's own list (its id or your uid) instead of the environment's.","examples":["user_8812"]},"suppressions":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","description":"The address to suppress."},"scope":{"type":"string","description":"`*` (the default) or a category."}},"required":["address"],"additionalProperties":false},"minItems":1,"maxItems":1000,"description":"1-1000 entries. Each one is validated on its own: invalid entries are skipped and reported in `invalid`, the rest are imported."}},"required":["suppressions"],"additionalProperties":false,"examples":[{"suppressions":[{"address":"user@example.com"},{"address":"other@example.com","scope":"marketing"}]}]},"DeletedSuppression":{"type":"object","properties":{"object":{"type":"string","enum":["suppression"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"suppression","id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"Subaccount":{"type":"object","properties":{"object":{"type":"string","enum":["subaccount"]},"id":{"type":"string","examples":["sub_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"uid":{"type":["string","null"],"description":"Your own id for it (e.g. your user's id), unique in the environment. Every path and send that takes a sub-account accepts its `id` or its `uid`."},"name":{"type":"string","description":"Your name for it."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"status":{"type":"string","enum":["active","disabled","deleting"],"description":"`disabled`: you turned it off (its sends are refused). `deleting`: its domains are being released."},"quotas":{"$ref":"#/components/schemas/SubaccountQuotas"},"reputation":{"$ref":"#/components/schemas/SubaccountReputation"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","uid","name","metadata","status","quotas","reputation","created_at","updated_at"],"examples":[{"object":"subaccount","id":"sub_01k7c8m4q2f3e9v6t5r1n0p8yz","uid":"user_8812","name":"Acme Bakery","metadata":{"plan":"pro"},"status":"active","quotas":{"recipients_per_day":5000,"recipients_per_second":5,"burst":50},"reputation":{"status":"good","trigger":null,"changed_at":null,"reinstated_at":null},"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"SubaccountQuotas":{"type":"object","properties":{"recipients_per_day":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"Recipients it may send to per day; `null`: only your organization's quota."},"recipients_per_second":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"Recipients it may send to per second; `null`: only your organization's quota."},"burst":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"How many recipients a moment may take before the per-second rate applies; `null`: the per-second rate."}},"required":["recipients_per_day","recipients_per_second","burst"],"description":"Its own sending limits.","examples":[{"recipients_per_day":5000,"recipients_per_second":5,"burst":50}]},"SubaccountReputation":{"type":"object","properties":{"status":{"type":"string","enum":["good","warning","paused"],"description":"`warning`: a rate is close to its limit. `paused`: its live sends are refused (`subaccount_paused`) until you reinstate it."},"trigger":{"type":["string","null"],"description":"What last changed it, e.g. `bounce_rate`, `complaint_rate`, `content_screening`."},"changed_at":{"type":["string","null"],"format":"date-time","description":"When its status last changed. `null`: never."},"reinstated_at":{"type":["string","null"],"format":"date-time","description":"When it was last reinstated. `null`: never."}},"required":["status","trigger","changed_at","reinstated_at"],"description":"Its own sending standing.","examples":[{"status":"good","trigger":null,"changed_at":null,"reinstated_at":null}]},"CreateSubaccountRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"A name for your own reference.","examples":["Acme Bakery"]},"uid":{"type":"string","description":"Your own id for it, to address it by instead of its `id`.","examples":["user_8812"]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs (at most 16; keys up to 40 characters, values up to 500).","examples":[{"plan":"pro"}]},"quotas":{"type":"object","properties":{"recipients_per_day":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"Most recipients a day. `null` removes the limit."},"recipients_per_second":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"Most recipients a second. `null` removes the limit."},"burst":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"How many recipients a moment may take before the per-second rate applies. `null` removes it."}},"additionalProperties":false,"description":"Fields left out keep their value; `null` removes a quota.","examples":[{"recipients_per_day":5000,"recipients_per_second":5,"burst":50}]}},"required":["name"],"additionalProperties":false,"examples":[{"name":"Acme Bakery","uid":"user_8812","quotas":{"recipients_per_day":5000}}]},"SubaccountList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Subaccount"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"subaccount","id":"sub_01k7c8m4q2f3e9v6t5r1n0p8yz","uid":"user_8812","name":"Acme Bakery","metadata":{"plan":"pro"},"status":"active","quotas":{"recipients_per_day":5000,"recipients_per_second":5,"burst":50},"reputation":{"status":"good","trigger":null,"changed_at":null,"reinstated_at":null},"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"SubaccountStats":{"type":"object","properties":{"object":{"type":"string","enum":["subaccount_stats"]},"subaccount_id":{"type":"string","description":"The sub-account's id."},"from":{"type":"string","format":"date","description":"The first date included."},"to":{"type":"string","format":"date","description":"The last date included."},"data":{"type":"array","items":{"$ref":"#/components/schemas/SubaccountStatsDay"},"description":"One entry per day with sends, oldest first; recipients count by their current status."}},"required":["object","subaccount_id","from","to","data"],"examples":[{"object":"subaccount_stats","subaccount_id":"sub_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"2026-10-15","to":"2026-10-15","data":[{"date":"2026-10-15","recipients":120,"sent":118,"delivered":115,"bounced":2,"complained":0,"failed":0,"suppressed":2}]}]},"SubaccountStatsDay":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"The UTC date."},"recipients":{"type":"integer","description":"Recipients of the emails sent that day."},"sent":{"type":"integer","description":"Handed to the provider (delivered or not)."},"delivered":{"type":"integer","description":"Deliveries that day."},"bounced":{"type":"integer","description":"Bounces that day."},"complained":{"type":"integer","description":"Complaints that day."},"failed":{"type":"integer","description":"Failures that day."},"suppressed":{"type":"integer","description":"Skipped: on a suppression list."}},"required":["date","recipients","sent","delivered","bounced","complained","failed","suppressed"],"examples":[{"date":"2026-10-15","recipients":120,"sent":118,"delivered":115,"bounced":2,"complained":0,"failed":0,"suppressed":2}]},"UpdateSubaccountRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Your name for it."},"uid":{"type":["string","null"],"description":"`null` removes it."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Replaces the metadata.","examples":[{"plan":"pro"}]},"status":{"type":"string","enum":["active","disabled"],"description":"`disabled` refuses its sends until it is `active` again."},"quotas":{"type":"object","properties":{"recipients_per_day":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"Most recipients a day. `null` removes the limit."},"recipients_per_second":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"Most recipients a second. `null` removes the limit."},"burst":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"How many recipients a moment may take before the per-second rate applies. `null` removes it."}},"additionalProperties":false,"description":"Fields left out keep their value; `null` removes a quota.","examples":[{"recipients_per_day":5000,"recipients_per_second":5,"burst":50}]}},"additionalProperties":false,"examples":[{"status":"disabled"}]},"Sms":{"type":"object","properties":{"object":{"type":"string","enum":["sms"]},"id":{"type":"string","examples":["sms_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"from":{"type":"string","description":"The number it's sent from, in E.164."},"to":{"type":"string","description":"The recipient's number, in E.164."},"body":{"type":"string","description":"The text. Empty once discarded."},"status":{"type":"string","enum":["queued","scheduled","sent","delivered","undelivered","failed","canceled"],"description":"`queued` until handed to the carrier (`sent`), then `delivered` or `undelivered` once the carrier reports. `failed`: never sent. `scheduled` and `canceled`: scheduled sends."},"segments":{"type":"integer","description":"Segments the body takes (what is billed)."},"encoding":{"type":"string","enum":["gsm7","ucs2"],"description":"`gsm7` fits the basic alphabet; `ucs2` is used for anything else, with smaller segments."},"country":{"type":"string","description":"ISO 3166 country of `to`.","examples":["US"]},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The tag's name."},"value":{"type":"string","description":"The tag's value."}},"required":["name","value"]},"description":"Your tags on the message."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"],"description":"Why the message failed or wasn't delivered."},"sandbox":{"type":"boolean","description":"Sent from a sandbox environment: simulated."},"scheduled_at":{"type":["string","null"],"format":"date-time","description":"When it's set to send. `null`: it was sent at once."},"sent_at":{"type":["string","null"],"format":"date-time","description":"When it was handed to the carrier. `null`: not yet."},"delivered_at":{"type":["string","null"],"format":"date-time","description":"When the carrier reported delivery. `null`: not delivered, or not reported."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","from","to","body","status","segments","encoding","country","tags","failure","sandbox","scheduled_at","sent_at","delivered_at","created_at"],"examples":[{"object":"sms","id":"sms_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"+14155550123","to":"+14155550199","body":"Your Acme code is 482913","status":"delivered","segments":1,"encoding":"gsm7","country":"US","tags":[{"name":"flow","value":"sign_in"}],"failure":null,"sandbox":false,"scheduled_at":null,"sent_at":"2026-11-10T12:00:01.000Z","delivered_at":"2026-11-10T12:00:04.000Z","created_at":"2026-11-10T12:00:00.000Z"}]},"SendSmsRequest":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"One of your organization's phone numbers, in E.164 form. Sandbox environments accept any number.","examples":["+14155550123"]},"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"The recipient's mobile number, in E.164 form.","examples":["+14155550199"]},"body":{"type":"string","minLength":1,"maxLength":1600,"description":"The text. Messages are split into segments of 153 GSM-7 or 67 Unicode characters (152 or 66 from a toll-free number; 160 or 70 for a single one), each billed; at most 10 (1,520 GSM-7 or 660 Unicode characters).","examples":["Your Acme code is 482913"]},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's name, unique on the message."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's value."}},"required":["name","value"],"additionalProperties":false},"maxItems":10,"description":"Up to 10 tags."},"scheduled_at":{"type":"string","format":"date-time","description":"Send at this time instead of now (ISO 8601 with an offset, at most 30 days ahead). A time that is not in the future sends immediately.","example":"2026-11-11T09:00:00Z"}},"required":["from","to","body"],"additionalProperties":false,"examples":[{"from":"+14155550123","to":"+14155550199","body":"Your Acme code is 482913","tags":[{"name":"flow","value":"sign_in"}]}]},"SmsList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Sms"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"SmsSuppression":{"type":"object","properties":{"object":{"type":"string","enum":["sms_suppression"]},"id":{"type":"string","examples":["smssup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"phone_number":{"type":"string","description":"The suppressed number, in E.164."},"reason":{"type":"string","enum":["opt_out","manual","invalid_number"],"description":"`opt_out`: the number replied STOP (or the carrier says it opted out). `invalid_number`: not a number that can receive SMS. `manual`: added by you."},"sms_id":{"type":["string","null"],"description":"The message whose failure added it, if any."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","phone_number","reason","sms_id","created_at"],"description":"A number sends skip.","examples":[{"object":"sms_suppression","id":"smssup_01k7c8m4q2f3e9v6t5r1n0p8yz","phone_number":"+14155550199","reason":"opt_out","sms_id":null,"created_at":"2026-11-10T12:05:00.000Z"}]},"CreateSmsSuppressionRequest":{"type":"object","properties":{"phone_number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"The number to suppress, in E.164."}},"required":["phone_number"],"additionalProperties":false,"examples":[{"phone_number":"+14155550199"}]},"SmsSuppressionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsSuppression"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"SmsSuppressionCheck":{"type":"object","properties":{"object":{"type":"string","enum":["sms_suppression_check"]},"phone_number":{"type":"string","description":"The number checked, in E.164."},"suppressed":{"type":"boolean","description":"Whether a send to this number would be skipped."},"suppression":{"allOf":[{"$ref":"#/components/schemas/SmsSuppression"},{"type":["object","null"]}]}},"required":["object","phone_number","suppressed","suppression"],"examples":[{"object":"sms_suppression_check","phone_number":"+14155550199","suppressed":false,"suppression":null}]},"DeletedSmsSuppression":{"type":"object","properties":{"object":{"type":"string","enum":["sms_suppression"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"sms_suppression","id":"smssup_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"ReceivedSmsList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedSms"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"ReceivedSms":{"type":"object","properties":{"object":{"type":"string","enum":["received_sms"]},"id":{"type":"string","examples":["smsin_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"from":{"type":"string","description":"Who sent it."},"to":{"type":"string","description":"Your number that received it."},"body":{"type":"string","description":"The text."},"segments":{"type":"integer","description":"Segments the text took."},"keyword":{"type":["string","null"],"enum":["stop","start","help",null],"description":"`stop`: an opt-out (the sender is suppressed in every live environment), `start`: an opt-in again, `help`: a request for help. Twilio answers each."},"sandbox":{"type":"boolean","description":"Whether it's a simulated message of a sandbox environment."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","from","to","body","segments","keyword","sandbox","created_at"],"examples":[{"object":"received_sms","id":"smsin_01k7c8m4q2f3e9v6t5r1n0p8yz","from":"+14155550199","to":"+14155550123","body":"Thanks, see you then!","segments":1,"keyword":null,"sandbox":false,"created_at":"2026-11-10T12:05:00.000Z"}]},"SmsNumberList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsNumber"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"SmsNumber":{"type":"object","properties":{"object":{"type":"string","enum":["sms_number"]},"id":{"type":"string","examples":["num_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"phone_number":{"type":"string","description":"The number, in E.164."},"kind":{"type":"string","enum":["local","toll_free"],"description":"`local` (US A2P 10DLC) or `toll_free` (toll-free verification, and sends only to the US and Canada)."},"country":{"type":"string","description":"Its country (ISO 3166-1 alpha-2)."},"status":{"type":"string","enum":["pending","active","releasing"],"description":"`pending`: not ready yet. `active`: ready, once its registration is approved. `releasing`: being given up."},"registration_status":{"type":["string","null"],"enum":["draft","submitted","in_review","approved","rejected","failed",null],"description":"Its carrier registration's status; live sends need `approved`."},"can_send":{"type":"boolean","description":"Whether live sends can go from it now."},"receives_here":{"type":"boolean","description":"Whether replies to it arrive in the environment of the key making the request."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","phone_number","kind","country","status","registration_status","can_send","receives_here","created_at"],"examples":[{"object":"sms_number","id":"num_01k7c8m4q2f3e9v6t5r1n0p8yz","phone_number":"+14155550123","kind":"local","country":"US","status":"active","registration_status":"approved","can_send":true,"receives_here":true,"created_at":"2026-11-01T09:00:00.000Z"}]},"SmsEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsEvent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"sms_event","id":"smsevt_01k7c8m4r0c2b8w9y3d5f6g7h8","sms_id":"sms_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"sms.delivered","occurred_at":"2026-11-10T12:00:04.000Z","data":{}}],"has_more":false}]},"SmsEvent":{"type":"object","properties":{"object":{"type":"string","enum":["sms_event"]},"id":{"type":"string"},"sms_id":{"type":"string","description":"The id of the message."},"type":{"type":"string","enum":["sms.scheduled","sms.sent","sms.delivered","sms.undelivered","sms.failed","sms.suppressed","sms.canceled"],"description":"What happened: `sms.scheduled`, `sms.sent`, `sms.delivered`, `sms.undelivered`, `sms.failed`, `sms.suppressed` or `sms.canceled`."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"data":{"$ref":"#/components/schemas/SmsEventData"}},"required":["object","id","sms_id","type","occurred_at","data"],"examples":[{"object":"sms_event","id":"smsevt_01k7c8m4r0c2b8w9y3d5f6g7h8","sms_id":"sms_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"sms.delivered","occurred_at":"2026-11-10T12:00:04.000Z","data":{}}]},"SmsEventData":{"type":"object","properties":{"failure":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"],"description":"Why the message failed or wasn't delivered."},"provider_error_code":{"type":["string","null"],"description":"The provider's or carrier's own error code, e.g. `30007`."},"suppression":{"type":"object","properties":{"id":{"type":"string","description":"The suppression's id."},"reason":{"type":"string","enum":["opt_out","manual","invalid_number"],"description":"Why the number is suppressed."}},"required":["id","reason"],"description":"`sms.suppressed`: the entry that made coss.com skip the number."}},"description":"Details of the event, where it has any."},"SignDocument":{"type":"object","properties":{"object":{"type":"string","enum":["sign_document"]},"id":{"type":"string","examples":["sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"filename":{"type":"string","description":"The file's name, as uploaded."},"size":{"type":"integer","description":"Bytes."},"sha256":{"type":"string","description":"Hex SHA-256 of the uploaded bytes."},"page_count":{"type":"integer","description":"How many pages it has."},"pages":{"type":"array","items":{"type":"object","properties":{"width":{"type":"number","description":"In PDF points (1/72 inch)."},"height":{"type":"number","description":"In PDF points (1/72 inch)."}},"required":["width","height"]},"description":"Each page's size, in order."},"anchors":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"The anchor as it appears in the document.","examples":["{{signature:signer_1}}"]},"page":{"type":"integer","description":"1-based page number."},"x":{"type":"number","description":"Left edge, in PDF points from the page's left."},"y":{"type":"number","description":"Top edge, in PDF points from the page's top."},"width":{"type":"number","description":"In PDF points."},"height":{"type":"number","description":"In PDF points."}},"required":["text","page","x","y","width","height"],"description":"A text anchor found in the document, in points from the page's top left."},"description":"Text anchors (`{{signature:signer_1}}`) found in the document, which fields can be placed by."},"sandbox":{"type":"boolean","description":"Whether it belongs to a sandbox environment."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","filename","size","sha256","page_count","pages","anchors","sandbox","created_at"],"examples":[{"object":"sign_document","id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz","filename":"agreement.pdf","size":48213,"sha256":"9f2c6c0f0e1d4b7a8c5e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c","page_count":2,"pages":[{"width":612,"height":792},{"width":612,"height":792}],"anchors":[{"text":"{{signature:signer_1}}","page":2,"x":72,"y":640,"width":140,"height":12}],"sandbox":false,"created_at":"2026-10-26T15:04:05.000Z"}]},"UploadSignDocumentRequest":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255,"description":"The file's name, ending in `.pdf`.","examples":["agreement.pdf"]},"content":{"type":"string","minLength":1,"description":"The PDF's bytes, base64-encoded (at most 25 MB decoded)."}},"required":["filename","content"],"additionalProperties":false,"examples":[{"filename":"agreement.pdf","content":"JVBERi0xLjcKJYGBgYEKCjEgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFsgNCAwIFIgXQovQ291bnQgMQo+PgplbmRvYmoKCjIgMCBvYmoKPDwKL1R5cGUgL0NhdGFsb2cKL1BhZ2VzIDEgMCBSCj4+CmVuZG9iagoKMyAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvVHlwZTEKL0Jhc2VGb250IC9IZWx2ZXRpY2EKL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcKPj4KZW5kb2JqCgo0IDAgb2JqCjw8Ci9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291cmNlcyA8PAovRm9udCA8PAovSGVsdmV0aWNhLTcwOTg0ODA3ODkgMyAwIFIKPj4KL1hPYmplY3QgPDwKPj4KL0V4dEdTdGF0ZSA8PAo+Pgo+PgovTWVkaWFCb3ggWyAwIDAgNjEyIDc5MiBdCi9Bbm5vdHMgWyBdCi9Db250ZW50cyBbIDUgMCBSIF0KPj4KZW5kb2JqCgo1IDAgb2JqCjw8Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggMTIwCj4+CnN0cmVhbQp4nG2KMQrCQBBF+znF1II4O7s7fxckYEjEwkaYC4hEiWgREc9vtLCSV/3330Stk/CHx4VWu+H2Gp7j6biE1JKKoFQOyn4mTex7Ct80MJQhwn6ndY5WDdZbQEKGWo4bFbQzf56fm3fexoAOXcN+JV9Q73SgN3RWIBIKZW5kc3RyZWFtCmVuZG9iagoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDE2IDAwMDAwIG4gCjAwMDAwMDAwNzYgMDAwMDAgbiAKMDAwMDAwMDEyNiAwMDAwMCBuIAowMDAwMDAwMjI0IDAwMDAwIG4gCjAwMDAwMDA0MTkgMDAwMDAgbiAKCnRyYWlsZXIKPDwKL1NpemUgNgovUm9vdCAyIDAgUgo+PgoKc3RhcnR4cmVmCjYxMgolJUVPRg=="}]},"SignDocumentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SignDocument"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"DeletedSignDocument":{"type":"object","properties":{"object":{"type":"string","enum":["sign_document"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"sign_document","id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"SignRequest":{"type":"object","properties":{"object":{"type":"string","enum":["sign_request"]},"id":{"type":"string","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"status":{"type":"string","enum":["draft","sent","completed","declined","canceled","expired"],"description":"`draft` until sent, `sent` while signers sign, then `completed` (everyone signed), `declined` (a signer declined), `canceled` or `expired`."},"title":{"type":"string","description":"Shown to signers."},"message":{"type":["string","null"],"description":"A note to signers. `null`: none."},"signing_order":{"type":"string","enum":["parallel","sequential"],"description":"`parallel`: everyone at once. `sequential`: in each signer's `order`."},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"filename":{"type":"string","description":"The file's name."},"sha256":{"type":"string","description":"Hex SHA-256 of the uploaded bytes."},"page_count":{"type":"integer","description":"How many pages it has."}},"required":["id","filename","sha256","page_count"]},"description":"The documents to sign, in order."},"signers":{"type":"array","items":{"$ref":"#/components/schemas/SignSigner"},"description":"Who signs."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SignField"},"description":"What each signer fills."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"sandbox":{"type":"boolean","description":"Whether it belongs to a sandbox environment."},"reminder_interval_days":{"type":["integer","null"],"description":"Days between automatic reminders to email signers; `null`: none."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When it expires if it isn't finished. `null`: never."},"expired_at":{"type":["string","null"],"format":"date-time","description":"When it expired. `null`: it hasn't."},"sent_at":{"type":["string","null"],"format":"date-time","description":"When it was sent. `null`: still a draft."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the last signer signed. `null`: not yet."},"canceled_at":{"type":["string","null"],"format":"date-time","description":"When it was canceled. `null`: it wasn't."},"declined_at":{"type":["string","null"],"format":"date-time","description":"When a signer declined it. `null`: nobody has."},"signed_document":{"anyOf":[{"type":"object","properties":{"sha256":{"type":"string","description":"Hex SHA-256 of the sealed PDF."},"sealed_at":{"type":"string","format":"date-time","description":"When it was sealed."}},"required":["sha256","sealed_at"]},{"type":"null"}],"description":"The completed document, sealed by coss.com: every document with the signatures and values filled in, and a certificate of completion. `null` until it is ready (shortly after `completed`, announced by the `sign_request.completed` webhook); download it from `GET /v1/sign/requests/{id}/signed_document`."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","status","title","message","signing_order","documents","signers","fields","metadata","sandbox","reminder_interval_days","expires_at","expired_at","sent_at","completed_at","canceled_at","declined_at","signed_document","created_at"],"examples":[{"object":"sign_request","id":"sreq_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"sent","title":"Services agreement","message":null,"signing_order":"parallel","documents":[{"id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz","filename":"agreement.pdf","sha256":"9f2c6c0f0e1d4b7a8c5e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c","page_count":2}],"signers":[{"object":"sign_signer","id":"ssgn_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Ada Lovelace","email":"ada@example.com","order":1,"delivery":"email","authentication":"email_link","status":"pending","client_ref":null,"viewed_at":null,"signed_at":null,"declined_at":null,"decline_reason":null}],"fields":[{"object":"sign_field","id":"sfld_01k7c8m4q2f3e9v6t5r1n0p8yz","signer_id":"ssgn_01k7c8m4q2f3e9v6t5r1n0p8yz","document_id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"signature","page":2,"x":72,"y":640,"width":140,"height":12,"required":true,"label":null,"anchor":"{{signature:signer_1}}"}],"metadata":{},"sandbox":false,"reminder_interval_days":3,"expires_at":null,"expired_at":null,"sent_at":"2026-10-26T15:04:05.000Z","completed_at":null,"canceled_at":null,"declined_at":null,"signed_document":null,"created_at":"2026-10-26T15:04:05.000Z"}]},"SignSigner":{"type":"object","properties":{"object":{"type":"string","enum":["sign_signer"]},"id":{"type":"string","examples":["ssgn_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"name":{"type":"string"},"email":{"type":"string"},"order":{"type":"integer","description":"Where they come in `signing_order: sequential`. Lower signs first."},"delivery":{"type":"string","enum":["embedded","email"],"description":"`email`: coss.com emails them a link. `embedded`: your app shows the signing page."},"authentication":{"type":"string","enum":["email_link","customer_asserted"],"description":"How the signer is identified: `email_link` (they opened the link coss.com emailed) or `customer_asserted` (your app vouched for them)."},"status":{"type":"string","enum":["pending","notified","viewed","signed","declined"],"description":"`pending`: not contacted yet. `notified`: emailed their link. `viewed`: opened the signing page. `signed`: done. `declined`: refused, which declines the whole request."},"client_ref":{"type":["string","null"],"description":"Your own id for the signer. `null`: none given."},"viewed_at":{"type":["string","null"],"format":"date-time","description":"When they first opened the signing page. `null`: not yet."},"signed_at":{"type":["string","null"],"format":"date-time","description":"When they signed. `null`: not yet."},"declined_at":{"type":["string","null"],"format":"date-time","description":"When they declined. `null`: they haven't."},"decline_reason":{"type":["string","null"],"description":"The reason they gave. `null`: none given."}},"required":["object","id","name","email","order","delivery","authentication","status","client_ref","viewed_at","signed_at","declined_at","decline_reason"],"description":"Someone asked to sign."},"SignField":{"type":"object","properties":{"object":{"type":"string","enum":["sign_field"]},"id":{"type":"string","examples":["sfld_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"signer_id":{"type":"string","description":"The id of the signer who fills it."},"document_id":{"type":"string","description":"The id of the document it's on."},"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"`signature` and `initials` take the signer's adopted signature, `date_signed` is filled with the signing date, `name` and `email` with the signer's, `text` and `checkbox` by the signer."},"page":{"type":"integer","description":"1-based page number."},"x":{"type":"number","description":"Left edge, in PDF points from the page's left."},"y":{"type":"number","description":"Top edge, in PDF points from the page's top."},"width":{"type":"number","description":"In PDF points."},"height":{"type":"number","description":"In PDF points."},"required":{"type":"boolean","description":"Whether a signer can finish with it empty."},"label":{"type":["string","null"],"description":"Shown to the signer. `null`: none."},"anchor":{"type":["string","null"],"description":"The text anchor it was placed by. `null`: placed by position."}},"required":["object","id","signer_id","document_id","type","page","x","y","width","height","required","label","anchor"],"description":"A box on a page that one signer fills."},"CreateSignRequestRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Shown to signers."},"message":{"type":"string","maxLength":2000,"description":"A note to signers."},"documents":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"document_id":{"type":"string","description":"An uploaded document.","examples":["sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"required":["document_id"],"additionalProperties":false},{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255,"description":"The file's name, ending in `.pdf`.","examples":["agreement.pdf"]},"content":{"type":"string","minLength":1,"description":"The PDF's bytes, base64-encoded (at most 25 MB decoded)."}},"required":["filename","content"],"additionalProperties":false}]},"minItems":1,"maxItems":10,"description":"Uploaded documents by id, or PDFs inline (base64)."},"signers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Shown on the signing page and on the certificate."},"email":{"type":"string","maxLength":254,"format":"email","description":"Where a `delivery: email` signer gets their link. Unique within a request."},"delivery":{"type":"string","enum":["embedded","email"],"description":"`email` (default): coss.com emails the signer a link. `embedded`: your app shows the signing page (create a session) and vouches for who the signer is."},"order":{"type":"integer","minimum":1,"maximum":20,"description":"With `signing_order: \"sequential\"`, signers sign in increasing `order` (default: their position in `signers`)."},"client_ref":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for the signer, recorded in the audit trail."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SignFieldInput"},"maxItems":500,"description":"What this signer fills. Every signer needs at least one `signature` field."}},"required":["name","email","fields"],"additionalProperties":false},"minItems":1,"maxItems":20,"description":"Who signs, and what each fills."},"signing_order":{"type":"string","enum":["parallel","sequential"],"description":"`parallel` (default): everyone at once. `sequential`: in each signer's `order`."},"expires_at":{"type":"string","format":"date-time","description":"When unsigned requests expire (at most 365 days ahead)."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs, returned with the request and its webhooks."},"reminder_interval_days":{"type":["integer","null"],"minimum":1,"maximum":30,"description":"Email signers who haven't signed get a reminder every this many days (up to 3). Default: your Sign settings' `reminder_interval_days`; `null`: none."},"send":{"type":"boolean","description":"Default `true`: send at once. `false` keeps a `draft` to send later."}},"required":["title","documents","signers"],"additionalProperties":false,"examples":[{"title":"Services agreement","documents":[{"document_id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"}],"signers":[{"name":"Ada Lovelace","email":"ada@example.com","fields":[{"type":"signature","anchor":"{{signature:signer_1}}"},{"type":"date_signed","page":2,"x":320,"y":640,"width":120,"height":18}]}]}]},"SignFieldInput":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"`signature` and `initials` take the signer's adopted signature, `date_signed` is filled with the signing date, `name` and `email` with the signer's, `text` and `checkbox` by the signer."},"required":{"type":"boolean","description":"Default `true`. A signer can't finish with a required field empty."},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Shown to the signer."},"document":{"type":"integer","minimum":0,"description":"Index of the document in `documents` (default 0)."},"page":{"type":"integer","minimum":1,"description":"1-based page number."},"x":{"type":"number","minimum":0,"description":"Left edge, in PDF points from the page's left."},"y":{"type":"number","minimum":0,"description":"Top edge, in PDF points from the page's top."},"width":{"type":"number","exclusiveMinimum":0,"description":"In PDF points."},"height":{"type":"number","exclusiveMinimum":0,"description":"In PDF points."}},"required":["type","page","x","y","width","height"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"`signature` and `initials` take the signer's adopted signature, `date_signed` is filled with the signing date, `name` and `email` with the signer's, `text` and `checkbox` by the signer."},"required":{"type":"boolean","description":"Default `true`. A signer can't finish with a required field empty."},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Shown to the signer."},"anchor":{"type":"string","pattern":"^\\{\\{[a-z_]+:[A-Za-z0-9_-]{1,64}\\}\\}$","description":"Place the field over every occurrence of this text in the documents (e.g. `{{signature:signer_1}}`)."},"width":{"type":"number","exclusiveMinimum":0,"description":"Default: the anchor text's width."},"height":{"type":"number","exclusiveMinimum":0,"description":"Default: the anchor text's height."},"offset_x":{"type":"number","description":"Points to move it right."},"offset_y":{"type":"number","description":"Points to move it down."}},"required":["type","anchor"],"additionalProperties":false}]},"SignRequestList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SignRequest"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"SignEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SignEvent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"SignEvent":{"type":"object","properties":{"object":{"type":"string","enum":["sign_event"]},"id":{"type":"string","examples":["sevt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"sequence":{"type":"integer","description":"1-based position in the request's trail."},"type":{"type":"string","enum":["created","sent","notified","viewed","consented","signed","declined","reminded","canceled","expired","completed","sealed"],"description":"What happened. `created`, `sent`, `canceled` and `expired` concern the request; `notified`, `reminded`, `viewed`, `consented`, `signed` and `declined` a signer; `completed` is the last signature and `sealed` the sealed document being ready."},"signer_id":{"type":["string","null"],"description":"The id of the signer it concerns. `null`: the whole request."},"actor":{"type":"string","enum":["api_key","signer","dashboard","system"],"description":"Who did it: your API key, a signer, a member in the dashboard, or coss.com."},"ip_address":{"type":["string","null"],"description":"The address the action came from. `null`: unknown, or coss.com acted."},"user_agent":{"type":["string","null"],"description":"The client's `User-Agent`. `null`: unknown."},"details":{"type":"object","properties":{"reason":{"type":"string","description":"`declined`: the signer's reason."},"document_sha256":{"type":"object","additionalProperties":{"type":"string"},"description":"Each document's SHA-256 at that moment, by document id."},"disclosure_sha256":{"type":"string","description":"SHA-256 of the consent text the signer accepted."},"field_ids":{"type":"array","items":{"type":"string"},"description":"`signed`: the fields the signer filled."},"signature_sha256":{"type":"string","description":"SHA-256 of the signature image the signer adopted."},"initials_sha256":{"type":"string","description":"SHA-256 of the initials image the signer adopted."},"session_id":{"type":"string","description":"The signing session the signer used."},"signed_document_sha256":{"type":"string","description":"`sealed`: the SHA-256 of the sealed, completed document."}},"description":"What this event recorded, depending on its type."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"previous_hash":{"type":["string","null"],"description":"The previous event's `hash`. `null` on the first event."},"hash":{"type":"string","description":"SHA-256 over this event and `previous_hash`: changing or removing an event breaks the chain from there on."}},"required":["object","id","sequence","type","signer_id","actor","ip_address","user_agent","details","occurred_at","previous_hash","hash"],"examples":[{"object":"sign_event","id":"sevt_01k7c8m4q2f3e9v6t5r1n0p8yz","sequence":1,"type":"created","signer_id":null,"actor":"api_key","ip_address":"203.0.113.7","user_agent":null,"details":{"document_sha256":{"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz":"9f2c6c0f0e1d4b7a8c5e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c"}},"occurred_at":"2026-10-26T15:04:05.000Z","previous_hash":null,"hash":"9f2c6c0f0e1d4b7a8c5e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c"}]},"DeletedSignRequest":{"type":"object","properties":{"object":{"type":"string","enum":["sign_request"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"sign_request","id":"sreq_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"SignSession":{"type":"object","properties":{"object":{"type":"string","enum":["sign_session"]},"id":{"type":"string","examples":["sgs_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"request_id":{"type":"string","description":"The signature request's id."},"signer_id":{"type":"string","description":"The signer's id."},"url":{"type":"string","description":"The signing page: embed it in an iframe (from an allowed origin, with `coss/sign`'s `mountSigning`) or redirect to it. The token is in the URL fragment, so it never reaches a server log: show it only to that signer."},"token":{"type":"string","description":"The secret part of `url`, shown only here."},"expires_at":{"type":"string","format":"date-time","description":"When the link stops working."}},"required":["object","id","request_id","signer_id","url","token","expires_at"],"examples":[{"object":"sign_session","id":"sgs_01k7c8m4q2f3e9v6t5r1n0p8yz","request_id":"sreq_01k7c8m4q2f3e9v6t5r1n0p8yz","signer_id":"ssgn_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://sign.example/s/sgs_01k7c8m4q2f3e9v6t5r1n0p8yz#cosss_…","token":"cosss_…","expires_at":"2026-10-26T15:04:05.000Z"}]},"CreateSignSessionRequest":{"type":"object","properties":{"expires_in":{"type":"integer","minimum":60,"maximum":86400,"description":"Seconds until the link expires: default 3600, at most 86400. Mint one when your user opens the page that shows it."}},"additionalProperties":false,"examples":[{"expires_in":3600}]},"SignSettings":{"type":"object","properties":{"object":{"type":"string","enum":["sign_settings"]},"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Origins that may embed the signing page in an iframe, like `https://app.example.com` (sandbox environments also `http://localhost:<port>`). Empty: it can only be opened on its own."},"display_name":{"type":["string","null"],"description":"The requester's name signers see. `null`: the organization's name."},"accent_color":{"type":["string","null"],"description":"The signing page's accent color, as `#RRGGBB`. `null`: the default."},"theme":{"type":"string","enum":["system","light","dark"],"description":"The signing page's theme. `system` follows the signer's device."},"disclosure":{"type":["string","null"],"description":"Your own consent text signers accept before they see a document. `null`: coss.com's default, which covers ESIGN's consumer disclosure. Have your counsel review a replacement."},"email_from":{"type":["string","null"],"description":"Signing emails (invitations, reminders, signed copies) come from this address, on a verified domain in live environments. `null`: from coss.com, as \"<display name> via coss.com\"."},"reminder_interval_days":{"type":["integer","null"],"description":"The default days between reminders for new requests; `null`: none."}},"required":["object","allowed_origins","display_name","accent_color","theme","disclosure","email_from","reminder_interval_days"],"examples":[{"object":"sign_settings","allowed_origins":["https://app.example.com"],"display_name":"Acme","accent_color":"#2563eb","theme":"system","disclosure":null,"email_from":"contracts@acme.com","reminder_interval_days":3}]},"UpdateSignSettingsRequest":{"type":"object","properties":{"allowed_origins":{"type":"array","items":{"type":"string","maxLength":255},"maxItems":10,"description":"Origins that may embed the signing page in an iframe, like `https://app.example.com` (sandbox environments also `http://localhost:<port>`). Empty: it can only be opened on its own."},"display_name":{"type":["string","null"],"maxLength":64,"description":"The requester's name signers see. `null`: the organization's name."},"accent_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","description":"The signing page's accent color, as `#RRGGBB`. `null`: the default."},"theme":{"type":"string","enum":["system","light","dark"],"description":"The signing page's theme. `system` follows the signer's device."},"disclosure":{"type":["string","null"],"minLength":1,"maxLength":10000,"description":"Your own consent text signers accept before they see a document. `null`: coss.com's default. Have your counsel review a replacement."},"email_from":{"type":["string","null"],"maxLength":254,"format":"email","description":"Signing emails come from this address, on a verified domain in live environments. `null`: from coss.com, as \"<display name> via coss.com\"."},"reminder_interval_days":{"type":["integer","null"],"minimum":1,"maximum":30,"description":"The default days between reminders for new requests. `null`: none."}},"additionalProperties":false,"description":"Only the fields given change.","examples":[{"allowed_origins":["https://app.example.com"],"display_name":"Acme"}]},"SignTemplate":{"type":"object","properties":{"object":{"type":"string","enum":["sign_template"]},"id":{"type":"string","examples":["stpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"name":{"type":"string","description":"Your name for the template."},"title":{"type":["string","null"],"description":"Requests' title. `null`: the template's name."},"message":{"type":["string","null"],"description":"Requests' message to signers. `null`: none."},"signing_order":{"type":"string","enum":["parallel","sequential"],"description":"Its requests' order, unless one sets its own."},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","description":"The file's name."},"sha256":{"type":"string","description":"Hex SHA-256 of the uploaded bytes."},"page_count":{"type":"integer","description":"How many pages it has."},"pages":{"type":"array","items":{"type":"object","properties":{"width":{"type":"number","description":"In PDF points (1/72 inch)."},"height":{"type":"number","description":"In PDF points (1/72 inch)."}},"required":["width","height"]},"description":"Each page's size, in order."}},"required":["id","filename","sha256","page_count","pages"]},"description":"The documents its requests use, in order."},"roles":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The role's id within the template."},"name":{"type":"string","description":"Shown in the builder, e.g. `Client`."}},"required":["key","name"]},"description":"Who signs: each request names one signer per role."},"fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","description":"The `key` of the role that fills it."},"document_id":{"type":"string","description":"The id of the document it's on."},"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"What the field takes, as on a signature request."},"page":{"type":"integer","description":"1-based page number."},"x":{"type":"number","description":"Left edge, in PDF points from the page's left."},"y":{"type":"number","description":"Top edge, in PDF points from the page's top."},"width":{"type":"number","description":"In PDF points."},"height":{"type":"number","description":"In PDF points."},"required":{"type":"boolean","description":"Whether a signer can finish with it empty."},"label":{"type":["string","null"],"description":"Shown to the signer. `null`: none."},"merge_key":{"type":["string","null"],"description":"`text` fields: which `merge_fields` value fills it. `null`: the signer fills it."}},"required":["id","role","document_id","type","page","x","y","width","height","required","label","merge_key"]},"description":"Each role's fields."},"ready":{"type":"boolean","description":"It has documents and every role has a `signature` field, so requests can be made from it."},"sandbox":{"type":"boolean","description":"Whether it belongs to a sandbox environment."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","title","message","signing_order","documents","roles","fields","ready","sandbox","created_at","updated_at"],"examples":[{"object":"sign_template","id":"stpl_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Mutual NDA","title":null,"message":null,"signing_order":"parallel","documents":[{"id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz","filename":"nda.pdf","sha256":"9f2c6c0f0e1d4b7a8c5e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c","page_count":1,"pages":[{"width":612,"height":792}]}],"roles":[{"key":"client","name":"Client"}],"fields":[{"id":"stfld_01k7c8m4q2f3e9v6t5r1n0p8yz","role":"client","document_id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz","type":"signature","page":1,"x":72,"y":640,"width":160,"height":30,"required":true,"label":null,"merge_key":null}],"ready":true,"sandbox":false,"created_at":"2026-10-26T15:04:05.000Z","updated_at":"2026-10-26T15:04:05.000Z"}]},"CreateSignTemplateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the template."},"title":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"Requests' title (a request may set its own). Default: `name`."},"message":{"type":["string","null"],"maxLength":5000,"description":"Requests' message to signers (a request may set its own)."},"signing_order":{"type":"string","enum":["parallel","sequential"],"description":"`parallel`: everyone at once. `sequential`: in each signer's `order`. Default for its requests."},"documents":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"document_id":{"type":"string","description":"An uploaded document.","examples":["sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"required":["document_id"],"additionalProperties":false},{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255,"description":"The file's name, ending in `.pdf`.","examples":["agreement.pdf"]},"content":{"type":"string","minLength":1,"description":"The PDF's bytes, base64-encoded (at most 25 MB decoded)."}},"required":["filename","content"],"additionalProperties":false}]},"maxItems":10,"description":"Uploaded documents by id, or PDFs inline (base64)."},"roles":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"The role's id within the template, used by fields and signers.","examples":["client"]},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Shown in the builder, e.g. `Client`."}},"required":["key","name"],"additionalProperties":false},"maxItems":20,"description":"Who signs: each request names one signer per role."},"fields":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"`signature` and `initials` take the signer's adopted signature, `date_signed` is filled with the signing date, `name` and `email` with the signer's, `text` and `checkbox` by the signer."},"required":{"type":"boolean","description":"Default `true`. A signer can't finish with a required field empty."},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Shown to the signer."},"document":{"type":"integer","minimum":0,"description":"Index of the document in `documents` (default 0)."},"page":{"type":"integer","minimum":1,"description":"1-based page number."},"x":{"type":"number","minimum":0,"description":"Left edge, in PDF points from the page's left."},"y":{"type":"number","minimum":0,"description":"Top edge, in PDF points from the page's top."},"width":{"type":"number","exclusiveMinimum":0,"description":"In PDF points."},"height":{"type":"number","exclusiveMinimum":0,"description":"In PDF points."},"role":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"The role's key, e.g. `client`.","examples":["client"]},"merge_key":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","description":"`text` fields only: filled from the request's `merge_fields[merge_key]` (shown to the signer, not editable). Without a value, the signer fills it."}},"required":["type","page","x","y","width","height","role"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"`signature` and `initials` take the signer's adopted signature, `date_signed` is filled with the signing date, `name` and `email` with the signer's, `text` and `checkbox` by the signer."},"required":{"type":"boolean","description":"Default `true`. A signer can't finish with a required field empty."},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Shown to the signer."},"anchor":{"type":"string","pattern":"^\\{\\{[a-z_]+:[A-Za-z0-9_-]{1,64}\\}\\}$","description":"Place the field over every occurrence of this text in the documents (e.g. `{{signature:signer_1}}`)."},"width":{"type":"number","exclusiveMinimum":0,"description":"Default: the anchor text's width."},"height":{"type":"number","exclusiveMinimum":0,"description":"Default: the anchor text's height."},"offset_x":{"type":"number","description":"Points to move it right."},"offset_y":{"type":"number","description":"Points to move it down."},"role":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"The role's key, e.g. `client`.","examples":["client"]},"merge_key":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","description":"`text` fields only: filled from the request's `merge_fields[merge_key]` (shown to the signer, not editable). Without a value, the signer fills it."}},"required":["type","anchor","role"],"additionalProperties":false}]},"maxItems":500,"description":"Each role's fields, by position or text anchor (resolved when saved). A template can be used once every role has a `signature` field."}},"required":["name"],"additionalProperties":false,"examples":[{"name":"Mutual NDA","documents":[{"document_id":"sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"}],"roles":[{"key":"client","name":"Client"},{"key":"company","name":"Company"}],"fields":[{"role":"client","type":"signature","anchor":"{{signature:client}}"},{"role":"client","type":"text","page":1,"x":72,"y":140,"width":200,"height":18,"merge_key":"client_company"},{"role":"company","type":"signature","anchor":"{{signature:company}}"}]}]},"SignTemplateList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SignTemplate"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"UpdateSignTemplateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the template."},"title":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"Requests' title (a request may set its own). Default: `name`."},"message":{"type":["string","null"],"maxLength":5000,"description":"Requests' message to signers (a request may set its own)."},"signing_order":{"type":"string","enum":["parallel","sequential"],"description":"`parallel`: everyone at once. `sequential`: in each signer's `order`. Default for its requests."},"documents":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"document_id":{"type":"string","description":"An uploaded document.","examples":["sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"required":["document_id"],"additionalProperties":false},{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255,"description":"The file's name, ending in `.pdf`.","examples":["agreement.pdf"]},"content":{"type":"string","minLength":1,"description":"The PDF's bytes, base64-encoded (at most 25 MB decoded)."}},"required":["filename","content"],"additionalProperties":false}]},"maxItems":10,"description":"Uploaded documents by id, or PDFs inline (base64)."},"roles":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"The role's id within the template, used by fields and signers.","examples":["client"]},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Shown in the builder, e.g. `Client`."}},"required":["key","name"],"additionalProperties":false},"maxItems":20,"description":"Who signs: each request names one signer per role."},"fields":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"`signature` and `initials` take the signer's adopted signature, `date_signed` is filled with the signing date, `name` and `email` with the signer's, `text` and `checkbox` by the signer."},"required":{"type":"boolean","description":"Default `true`. A signer can't finish with a required field empty."},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Shown to the signer."},"document":{"type":"integer","minimum":0,"description":"Index of the document in `documents` (default 0)."},"page":{"type":"integer","minimum":1,"description":"1-based page number."},"x":{"type":"number","minimum":0,"description":"Left edge, in PDF points from the page's left."},"y":{"type":"number","minimum":0,"description":"Top edge, in PDF points from the page's top."},"width":{"type":"number","exclusiveMinimum":0,"description":"In PDF points."},"height":{"type":"number","exclusiveMinimum":0,"description":"In PDF points."},"role":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"The role's key, e.g. `client`.","examples":["client"]},"merge_key":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","description":"`text` fields only: filled from the request's `merge_fields[merge_key]` (shown to the signer, not editable). Without a value, the signer fills it."}},"required":["type","page","x","y","width","height","role"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"],"description":"`signature` and `initials` take the signer's adopted signature, `date_signed` is filled with the signing date, `name` and `email` with the signer's, `text` and `checkbox` by the signer."},"required":{"type":"boolean","description":"Default `true`. A signer can't finish with a required field empty."},"label":{"type":"string","minLength":1,"maxLength":100,"description":"Shown to the signer."},"anchor":{"type":"string","pattern":"^\\{\\{[a-z_]+:[A-Za-z0-9_-]{1,64}\\}\\}$","description":"Place the field over every occurrence of this text in the documents (e.g. `{{signature:signer_1}}`)."},"width":{"type":"number","exclusiveMinimum":0,"description":"Default: the anchor text's width."},"height":{"type":"number","exclusiveMinimum":0,"description":"Default: the anchor text's height."},"offset_x":{"type":"number","description":"Points to move it right."},"offset_y":{"type":"number","description":"Points to move it down."},"role":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"The role's key, e.g. `client`.","examples":["client"]},"merge_key":{"type":"string","pattern":"^[A-Za-z0-9_]{1,64}$","description":"`text` fields only: filled from the request's `merge_fields[merge_key]` (shown to the signer, not editable). Without a value, the signer fills it."}},"required":["type","anchor","role"],"additionalProperties":false}]},"maxItems":500,"description":"Each role's fields, by position or text anchor (resolved when saved). A template can be used once every role has a `signature` field."}},"additionalProperties":false,"description":"Only the fields given change; `documents`, `roles` and `fields` replace the whole list (fields refer to documents by their new positions).","examples":[{"name":"Mutual NDA (2026)"}]},"DeletedSignTemplate":{"type":"object","properties":{"object":{"type":"string","enum":["sign_template"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"sign_template","id":"stpl_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"CreateSignRequestFromTemplateRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Default: the template's title (else its name)."},"message":{"type":"string","maxLength":5000,"description":"Default: the template's message."},"signers":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"The `key` of the template's role they sign as.","examples":["client"]},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Shown on the signing page and on the certificate."},"email":{"type":"string","maxLength":254,"format":"email","description":"Where a `delivery: email` signer gets their link."},"delivery":{"type":"string","enum":["embedded","email"],"description":"`email` (default): coss.com emails the signer a link. `embedded`: your app shows the signing page."},"order":{"type":"integer","minimum":1,"maximum":20,"description":"With `sequential` signing, signers sign in increasing `order`."},"client_ref":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for the signer, recorded in the audit trail."}},"required":["role","name","email"],"additionalProperties":false},"minItems":1,"maxItems":20,"description":"One signer for each of the template's roles."},"merge_fields":{"type":"object","additionalProperties":{"type":"string","maxLength":1000},"description":"Values of the template's merge fields, by `merge_key`."},"signing_order":{"type":"string","enum":["parallel","sequential"],"description":"Default: the template's."},"expires_at":{"type":"string","format":"date-time","description":"When an unfinished request expires, at most 365 days ahead."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs, returned with the request and its webhooks."},"reminder_interval_days":{"type":["integer","null"],"minimum":1,"maximum":30,"description":"Days between reminders to email signers. Default: your Sign settings'. `null`: none."},"send":{"type":"boolean","description":"Default `true`."}},"required":["signers"],"additionalProperties":false,"examples":[{"signers":[{"role":"client","name":"Ada Lovelace","email":"ada@example.com"},{"role":"company","name":"Grace Hopper","email":"grace@acme.com","delivery":"embedded"}],"merge_fields":{"client_company":"Analytical Engines Ltd"}}]},"SignBuilderSession":{"type":"object","properties":{"object":{"type":"string","enum":["sign_builder_session"]},"id":{"type":"string","examples":["sbs_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"template_id":{"type":"string","description":"The id of the template it edits."},"url":{"type":"string","description":"The builder: embed it (from an allowed origin, `mountBuilder` from `coss/sign`) for whoever edits the template: they can upload documents, add roles and place fields. Show it only to them."},"token":{"type":"string","description":"The secret part of `url`, shown only here."},"expires_at":{"type":"string","format":"date-time","description":"When the link stops working."}},"required":["object","id","template_id","url","token","expires_at"],"examples":[{"object":"sign_builder_session","id":"sbs_01k7c8m4q2f3e9v6t5r1n0p8yz","template_id":"stpl_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://sign.example/b/sbs_01k7c8m4q2f3e9v6t5r1n0p8yz#cossb_…","token":"cossb_…","expires_at":"2026-10-26T15:04:05.000Z"}]},"CreateSignBuilderSessionRequest":{"type":"object","properties":{"expires_in":{"type":"integer","minimum":60,"maximum":86400,"description":"Seconds until the link expires: default 3600, at most 86400."}},"additionalProperties":false,"examples":[{"expires_in":3600}]},"Verification":{"type":"object","properties":{"object":{"type":"string","enum":["verification"]},"id":{"type":"string","examples":["vrf_01k8e2m4q2f3e9v6t5r1n0p8yz"]},"channel":{"type":"string","enum":["sms","email"],"description":"`sms` or `email`."},"to":{"type":"string","description":"The phone number (E.164) or address the code goes to."},"country":{"type":["string","null"],"description":"ISO 3166 country of a phone number."},"status":{"type":"string","enum":["pending","approved","expired","canceled","failed","blocked"],"description":"`pending` until the right code is checked (`approved`) or it ends: `expired`, `canceled`, `failed` (too many wrong codes, or the code couldn't be sent) or `blocked` (the fraud guard stopped it before anything was sent)."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"],"description":"Why it `failed`."},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"value":{"type":"number"}},"required":["code"],"description":"A fraud guard reason (see the docs' list)."},"description":"Why it was `blocked` (empty otherwise)."},"attempts":{"type":"integer","description":"Wrong codes checked so far."},"max_attempts":{"type":"integer","description":"How many wrong codes end it."},"sends":{"type":"array","items":{"$ref":"#/components/schemas/VerificationSend"},"description":"Each time the code was sent."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The tag's name."},"value":{"type":"string","description":"The tag's value."}},"required":["name","value"]},"description":"Your tags on the verification."},"sandbox":{"type":"boolean","description":"Made in a sandbox environment: simulated, and the code is always zeros."},"expires_at":{"type":"string","format":"date-time","description":"When the code stops working."},"approved_at":{"type":["string","null"],"format":"date-time","description":"When the right code was checked. `null`: it wasn't."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","channel","to","country","status","failure","reasons","attempts","max_attempts","sends","tags","sandbox","expires_at","approved_at","created_at"],"examples":[{"object":"verification","id":"vrf_01k8e2m4q2f3e9v6t5r1n0p8yz","channel":"sms","to":"+14155550199","country":"US","status":"pending","failure":null,"reasons":[],"attempts":0,"max_attempts":5,"sends":[{"channel":"sms","route":"shared_number","sms_id":"sms_01k8e2m4q2f3e9v6t5r1n0p8yz","email_id":null,"created_at":"2026-11-10T12:00:00.000Z"}],"tags":[],"sandbox":false,"expires_at":"2026-11-10T12:10:00.000Z","approved_at":null,"created_at":"2026-11-10T12:00:00.000Z"}]},"VerificationSend":{"type":"object","properties":{"channel":{"type":"string","enum":["sms","email"],"description":"`sms` or `email`."},"route":{"type":"string","enum":["own_number","shared_number","email","coss_email"],"description":"`own_number`: one of your numbers; `shared_number`: coss.com's; `email`: your sender; `coss_email`: coss.com's sender."},"sms_id":{"type":["string","null"],"description":"The SMS, in your environment: `own_number`, or any in a sandbox environment (`null` for coss.com's shared numbers' messages)."},"email_id":{"type":["string","null"],"description":"The email (`email` route only)."},"created_at":{"type":"string","format":"date-time"}},"required":["channel","route","sms_id","email_id","created_at"]},"StartVerificationRequest":{"type":"object","properties":{"to":{"type":"string","minLength":1,"maxLength":320,"description":"Where the code goes: a mobile number in E.164 form, or an email address. A pending verification to the same destination and channel is reused: its code is sent again.","examples":["+14155550199"]},"channel":{"type":"string","enum":["sms","email"],"description":"`sms` or `email`. Default: `sms` for a phone number, `email` for an address."},"ip":{"type":"string","maxLength":64,"description":"The end user's IP address. The fraud guard uses it (velocity, Tor); recommended.","examples":["203.0.113.7"]},"user_id":{"type":"string","minLength":1,"maxLength":256,"description":"Your id for the end user, for the fraud guard's velocity and your Risk lists.","examples":["user_42"]},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}},"required":["name","value"],"additionalProperties":false},"maxItems":10,"description":"Up to 10 tags."}},"required":["to"],"additionalProperties":false,"examples":[{"to":"+14155550199","ip":"203.0.113.7","user_id":"user_42"}]},"VerificationCheck":{"type":"object","properties":{"object":{"type":"string","enum":["verification_check"]},"valid":{"type":"boolean","description":"Whether the code is right. Only `true` proves the end user has the phone or mailbox; checking an approved verification again with its code stays `true` until it expires."},"verification":{"$ref":"#/components/schemas/Verification"}},"required":["object","valid","verification"],"examples":[{"object":"verification_check","valid":true,"verification":{"object":"verification","id":"vrf_01k8e2m4q2f3e9v6t5r1n0p8yz","channel":"sms","to":"+14155550199","country":"US","status":"approved","failure":null,"reasons":[],"attempts":0,"max_attempts":5,"sends":[],"tags":[],"sandbox":false,"expires_at":"2026-11-10T12:10:00.000Z","approved_at":"2026-11-10T12:00:41.000Z","created_at":"2026-11-10T12:00:00.000Z"}}]},"CheckVerificationRequest":{"type":"object","properties":{"verification_id":{"type":"string","maxLength":64,"description":"The verification to check. Give this or `to`.","examples":["vrf_01k8e2m4q2f3e9v6t5r1n0p8yz"]},"to":{"type":"string","minLength":1,"maxLength":320,"description":"The destination the code was sent to: checks its most recent verification. Give this or `verification_id`.","examples":["+14155550199"]},"code":{"type":"string","pattern":"^\\d{4,10}$","description":"The code the end user entered.","examples":["482913"]}},"required":["code"],"additionalProperties":false,"examples":[{"to":"+14155550199","code":"482913"}]},"VerificationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Verification"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"VerifySettings":{"type":"object","properties":{"object":{"type":"string","enum":["verify_settings"]},"app_name":{"type":"string","description":"The name codes are sent for."},"app_name_is_default":{"type":"boolean","description":"Whether `app_name` is the project's: no name of its own is set."},"code_length":{"type":"integer","description":"Digits in a code."},"ttl_seconds":{"type":"integer","description":"How long a code works."},"max_attempts":{"type":"integer","description":"Wrong codes before a verification fails."},"sms_from":{"type":["string","null"],"description":"One of the organization's numbers; `null`: coss.com's shared numbers."},"email_from":{"type":["string","null"],"description":"An address on one of the organization's verified domains; `null`: coss.com's."},"allowed_countries":{"type":"array","items":{"type":"string"},"description":"ISO 3166 countries SMS codes may go to."}},"required":["object","app_name","app_name_is_default","code_length","ttl_seconds","max_attempts","sms_from","email_from","allowed_countries"],"description":"An environment's Verify settings.","examples":[{"object":"verify_settings","app_name":"Acme","app_name_is_default":false,"code_length":6,"ttl_seconds":600,"max_attempts":5,"sms_from":"+14155550100","email_from":"codes@acme.com","allowed_countries":["CA","US"]}]},"UpdateVerifySettingsRequest":{"type":"object","properties":{"app_name":{"type":["string","null"],"minLength":1,"maxLength":40,"description":"The name codes are sent for; `null`: the project's."},"code_length":{"type":"integer","minimum":4,"maximum":10,"description":"Digits in a code, 4-10."},"ttl_seconds":{"type":"integer","minimum":60,"maximum":1800,"description":"How long a code works, 60-1800 s."},"max_attempts":{"type":"integer","minimum":1,"maximum":10,"description":"Wrong codes before a verification fails, 1-10."},"sms_from":{"type":["string","null"],"pattern":"^\\+[1-9]\\d{6,14}$","description":"One of the organization's numbers; `null`: coss.com's shared numbers."},"email_from":{"type":["string","null"],"format":"email","description":"An address on one of the organization's verified domains (live keys); `null`: coss.com's."},"allowed_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"maxItems":250,"description":"ISO 3166 countries SMS codes may go to."}},"additionalProperties":false,"description":"Only the fields given change.","examples":[{"sms_from":"+14155550100","allowed_countries":["CA","GB","US"]}]},"Form":{"type":"object","properties":{"object":{"type":"string","enum":["form"]},"id":{"type":"string","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"name":{"type":"string","description":"Your name for the form, shown in the dashboard and in notifications."},"enabled":{"type":"boolean","description":"`false`: submissions are refused."},"endpoint":{"type":"string","description":"Where the form posts: `<form action=…>`."},"hosted_url":{"type":["string","null"],"description":"The hosted page, when `hosted.enabled`; `null` otherwise."},"fields":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FormField"},"description":"The form's fields. `null`: any field is accepted, without validation."},"strict_fields":{"type":"boolean","description":"With `fields`: whether fields the form doesn't define are refused."},"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Sites that may post to the form. Empty: any."},"redirect_url":{"type":["string","null"],"description":"Where browsers go after an HTML post. `null`: coss.com's thank-you page."},"spam":{"type":"object","properties":{"honeypot_field":{"type":"string","description":"A field people leave empty; a submission that fills it is spam."},"captcha":{"type":"string","enum":["off","required"],"description":"`required`: submissions need a captcha token. `off`: they don't."},"captcha_site_key":{"type":["string","null"],"description":"The captcha's site key, which hosted pages render the widget with. `null`: none set."},"content_threshold":{"type":["number","null"],"description":"A submission whose text scores at least this in a content category is spam. `null`: the environment's risk settings decide."},"on_review":{"type":"string","enum":["deliver","hold"],"description":"When Risk's decision is `review`: `hold` keeps the submission until you release it, `deliver` delivers it."}},"required":["honeypot_field","captcha","captcha_site_key","content_threshold","on_review"],"description":"How submissions are screened."},"submitter":{"type":"object","properties":{"email_field":{"type":"string","description":"The field holding the submitter's email address."},"verify":{"type":"boolean","description":"Whether submissions wait until the submitter clicks a link emailed to them."},"confirmation_from":{"type":["string","null"],"description":"The verification email's sender. `null`: none set."}},"required":["email_field","verify","confirmation_from"],"description":"Who the submitter is, and whether they must confirm by email."},"notifications":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"Who gets an email for each accepted submission."},"from":{"type":["string","null"],"description":"The notification's sender. `null`: coss.com, as \"<form name> via coss.com\"."}},"required":["recipients","from"],"description":"Emails about accepted submissions."},"contacts":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether each accepted submission becomes a contact."},"audience_ids":{"type":"array","items":{"type":"string"},"description":"Audiences the contact joins."},"topics":{"type":"array","items":{"type":"string"},"description":"Topic keys the contact is opted into."},"double_opt_in":{"type":["boolean","null"],"description":"Whether new contacts confirm by email first. `null`: the environment's marketing settings decide."},"first_name_field":{"type":["string","null"],"description":"The field holding the contact's first name. `null`: none."},"last_name_field":{"type":["string","null"],"description":"The field holding the contact's last name. `null`: none."},"properties":{"type":"object","additionalProperties":{"type":"string"},"description":"Contact property key → the field whose value it takes."}},"required":["enabled","audience_ids","topics","double_opt_in","first_name_field","last_name_field","properties"],"description":"Turning submissions into contacts."},"files":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether uploads are accepted (`multipart/form-data`)."},"max_files":{"type":"integer","description":"Most files per submission."},"max_file_bytes":{"type":"integer","description":"Largest file, in bytes."},"allowed_types":{"type":"array","items":{"type":"string"},"description":"MIME types accepted. Empty: images, PDFs, text and Office."}},"required":["enabled","max_files","max_file_bytes","allowed_types"],"description":"File uploads."},"hosted":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the page is served at `hosted_url`."},"title":{"type":["string","null"],"description":"The page's heading. `null`: the form's name."},"description":{"type":["string","null"],"description":"Text under the heading. `null`: none."},"submit_label":{"type":["string","null"],"description":"The submit button's label. `null`: the default."},"success_message":{"type":["string","null"],"description":"Shown after a submission. `null`: the default."},"published_at":{"type":["string","null"],"format":"date-time","description":"When the page was turned on, or what it shows last changed. `null`: never published."}},"required":["enabled","title","description","submit_label","success_message","published_at"],"description":"The page coss.com can serve for this form."},"disabled_by_admin":{"type":"boolean","description":"coss.com disabled the form for abuse; contact support."},"sandbox":{"type":"boolean","description":"Whether the form belongs to a sandbox environment."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","enabled","endpoint","hosted_url","fields","strict_fields","allowed_origins","redirect_url","spam","submitter","notifications","contacts","files","hosted","disabled_by_admin","sandbox","created_at","updated_at"],"examples":[{"object":"form","id":"form_01kd2m8n3p4q5r6s7t8v9w0x1y","name":"Contact us","enabled":true,"endpoint":"https://cossforms.com/f/form_01kd2m8n3p4q5r6s7t8v9w0x1y","hosted_url":null,"fields":null,"strict_fields":false,"allowed_origins":["https://www.example.com"],"redirect_url":null,"spam":{"honeypot_field":"_gotcha","captcha":"off","captcha_site_key":null,"content_threshold":0.9,"on_review":"hold"},"submitter":{"email_field":"email","verify":false,"confirmation_from":null},"notifications":{"recipients":["support@example.com"],"from":null},"contacts":{"enabled":false,"audience_ids":[],"topics":[],"double_opt_in":null,"first_name_field":null,"last_name_field":null,"properties":{}},"files":{"enabled":false,"max_files":3,"max_file_bytes":10485760,"allowed_types":[]},"hosted":{"enabled":false,"title":null,"description":null,"submit_label":null,"success_message":null,"published_at":null},"disabled_by_admin":false,"sandbox":false,"created_at":"2026-10-29T10:00:00.000Z","updated_at":"2026-10-29T10:00:00.000Z"}]},"FormField":{"type":"object","properties":{"name":{"type":"string","description":"The `name` the form's input posts."},"type":{"type":"string","enum":["text","email","textarea","number","tel","url","date","select","radio","checkbox","hidden","file"],"description":"Validates the value and picks the input on hosted pages."},"label":{"type":["string","null"],"description":"Shown on hosted pages and in notifications. `null`: the name."},"required":{"type":"boolean","description":"Whether a submission must include it."},"placeholder":{"type":["string","null"],"description":"Shown in the empty input on hosted pages. `null`: none."},"options":{"type":"array","items":{"type":"string"},"description":"The choices of `select`, `radio` and `checkbox` fields. Empty for other types."},"max_length":{"type":["integer","null"],"description":"The longest value accepted, in characters. `null`: only the overall limit."}},"required":["name","type","label","required","placeholder","options","max_length"]},"CreateFormRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Your name for the form, shown in the dashboard and in notifications."},"enabled":{"type":"boolean","description":"`false`: submissions are refused."},"fields":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FormFieldInput"},"maxItems":50,"description":"The form's fields. `null` (default): any field is accepted. With fields, submissions are validated against them."},"strict_fields":{"type":"boolean","description":"With `fields`: refuse fields the form doesn't define. Default false."},"allowed_origins":{"type":"array","items":{"type":"string","maxLength":255},"maxItems":10,"description":"Sites that may post to the form, like `https://www.example.com` (sandbox environments also `http://localhost:<port>`). Empty (default): any."},"redirect_url":{"type":["string","null"],"maxLength":2048,"format":"uri","description":"Where browsers go after an HTML post. `null`: coss.com's thank-you page. A post's `_next` field overrides it when its origin is allowed."},"spam":{"type":"object","properties":{"honeypot_field":{"type":"string","pattern":"^_?[A-Za-z0-9][A-Za-z0-9_-]{0,63}$","description":"A field people leave empty (hide it with CSS); a submission that fills it is spam. Default `_gotcha`."},"captcha":{"type":"string","enum":["off","required"],"description":"`required`: submissions need a token from the captcha set in the environment's risk settings (Turnstile or hCaptcha). Default `off`."},"captcha_site_key":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"The captcha's site key, which hosted pages render the widget with."},"content_threshold":{"type":["number","null"],"minimum":0.5,"maximum":1,"description":"A submission whose text scores at least this in a content category (spam, phishing, malware, fraud) is spam. Default 0.9; `null` leaves content to the environment's risk settings."},"on_review":{"type":"string","enum":["deliver","hold"],"description":"What happens when Risk's decision is `review`: `hold` (default) keeps the submission until you release it, `deliver` delivers it."}},"additionalProperties":false,"description":"How submissions are screened. Only the fields given change."},"submitter":{"type":"object","properties":{"email_field":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The field holding the submitter's email address (Risk checks it, notifications reply to it, contacts are made from it). Default `email`."},"verify":{"type":"boolean","description":"Hold every submission until the submitter clicks the link emailed to them (double opt-in for the whole submission). Default false."},"confirmation_from":{"type":["string","null"],"maxLength":254,"format":"email","description":"The verification email's sender: an address on a verified domain (required with `verify` in live environments)."}},"additionalProperties":false,"description":"Who the submitter is, and whether they must confirm by email. Only the fields given change."},"notifications":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":5,"description":"Who gets an email for each accepted submission: members of your organization, or addresses on its verified domains."},"from":{"type":["string","null"],"maxLength":254,"format":"email","description":"The notification's sender, on a verified domain in live environments. `null`: coss.com, as \"<form name> via coss.com\"."}},"additionalProperties":false,"description":"Emails about accepted submissions. Only the fields given change."},"contacts":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Turn each accepted submission into a contact, from `submitter.email_field`. Default false."},"audience_ids":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20,"description":"Audiences the contact joins. They must exist in this environment."},"topics":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"description":"Topic keys the contact is opted into."},"double_opt_in":{"type":["boolean","null"],"description":"New contacts confirm their subscription by email first. `null` (default): the environment's marketing settings decide."},"first_name_field":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The field holding the contact's first name. `null`: none."},"last_name_field":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The field holding the contact's last name. `null`: none."},"properties":{"type":"object","additionalProperties":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The `name` the form's input posts."},"description":"Contact property key → the field whose value it takes."}},"additionalProperties":false,"description":"Turning submissions into contacts. Only the fields given change."},"files":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Accept uploads (`multipart/form-data`). Default false."},"max_files":{"type":"integer","minimum":1,"maximum":10,"description":"Most files per submission. Default 3."},"max_file_bytes":{"type":"integer","minimum":1,"maximum":10485760,"description":"Largest file, in bytes. Default and maximum 10 MB."},"allowed_types":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9.+-]+\\/([a-z0-9.+-]+|\\*)$"},"maxItems":50,"description":"MIME types (`image/*` allowed). Empty: images, PDFs, text and Office."}},"additionalProperties":false,"description":"File uploads. Only the fields given change."},"hosted":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Serve the form as a page at its `hosted_url` (needs `fields`). Default false."},"title":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"The page's heading. `null`: the form's name."},"description":{"type":["string","null"],"maxLength":2000,"description":"Text under the heading. `null`: none."},"submit_label":{"type":["string","null"],"minLength":1,"maxLength":60,"description":"The submit button's label. `null`: the default."},"success_message":{"type":["string","null"],"minLength":1,"maxLength":500,"description":"Shown after a submission. `null`: the default."}},"additionalProperties":false,"description":"The page coss.com can serve for this form. Only the fields given change."}},"required":["name"],"additionalProperties":false,"examples":[{"name":"Contact us","allowed_origins":["https://www.example.com"],"notifications":{"recipients":["support@example.com"]}}]},"FormFieldInput":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The `name` the form's input posts."},"type":{"type":"string","enum":["text","email","textarea","number","tel","url","date","select","radio","checkbox","hidden","file"],"description":"Validates the value (`email`, `number`, `url`, `date` as `YYYY-MM-DD`, `select`/`radio` one of `options`, `checkbox` any of them or `on`) and picks the input on hosted pages. `file` needs uploads on (`files.enabled`)."},"label":{"type":"string","minLength":1,"maxLength":200,"description":"Shown on hosted pages and in notifications. Default: the name."},"required":{"type":"boolean","description":"Default false."},"placeholder":{"type":"string","maxLength":200,"description":"Shown in the empty input on hosted pages."},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":50,"description":"The choices of `select`, `radio` and `checkbox` fields."},"max_length":{"type":"integer","minimum":1,"maximum":10000,"description":"The longest value accepted, in characters."}},"required":["name","type"],"additionalProperties":false},"FormList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Form"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"UpdateFormRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Your name for the form, shown in the dashboard and in notifications."},"enabled":{"type":"boolean","description":"`false`: submissions are refused."},"fields":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FormFieldInput"},"maxItems":50,"description":"The form's fields. `null` (default): any field is accepted. With fields, submissions are validated against them."},"strict_fields":{"type":"boolean","description":"With `fields`: refuse fields the form doesn't define. Default false."},"allowed_origins":{"type":"array","items":{"type":"string","maxLength":255},"maxItems":10,"description":"Sites that may post to the form, like `https://www.example.com` (sandbox environments also `http://localhost:<port>`). Empty (default): any."},"redirect_url":{"type":["string","null"],"maxLength":2048,"format":"uri","description":"Where browsers go after an HTML post. `null`: coss.com's thank-you page. A post's `_next` field overrides it when its origin is allowed."},"spam":{"type":"object","properties":{"honeypot_field":{"type":"string","pattern":"^_?[A-Za-z0-9][A-Za-z0-9_-]{0,63}$","description":"A field people leave empty (hide it with CSS); a submission that fills it is spam. Default `_gotcha`."},"captcha":{"type":"string","enum":["off","required"],"description":"`required`: submissions need a token from the captcha set in the environment's risk settings (Turnstile or hCaptcha). Default `off`."},"captcha_site_key":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"The captcha's site key, which hosted pages render the widget with."},"content_threshold":{"type":["number","null"],"minimum":0.5,"maximum":1,"description":"A submission whose text scores at least this in a content category (spam, phishing, malware, fraud) is spam. Default 0.9; `null` leaves content to the environment's risk settings."},"on_review":{"type":"string","enum":["deliver","hold"],"description":"What happens when Risk's decision is `review`: `hold` (default) keeps the submission until you release it, `deliver` delivers it."}},"additionalProperties":false,"description":"How submissions are screened. Only the fields given change."},"submitter":{"type":"object","properties":{"email_field":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The field holding the submitter's email address (Risk checks it, notifications reply to it, contacts are made from it). Default `email`."},"verify":{"type":"boolean","description":"Hold every submission until the submitter clicks the link emailed to them (double opt-in for the whole submission). Default false."},"confirmation_from":{"type":["string","null"],"maxLength":254,"format":"email","description":"The verification email's sender: an address on a verified domain (required with `verify` in live environments)."}},"additionalProperties":false,"description":"Who the submitter is, and whether they must confirm by email. Only the fields given change."},"notifications":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string","maxLength":254,"format":"email"},"maxItems":5,"description":"Who gets an email for each accepted submission: members of your organization, or addresses on its verified domains."},"from":{"type":["string","null"],"maxLength":254,"format":"email","description":"The notification's sender, on a verified domain in live environments. `null`: coss.com, as \"<form name> via coss.com\"."}},"additionalProperties":false,"description":"Emails about accepted submissions. Only the fields given change."},"contacts":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Turn each accepted submission into a contact, from `submitter.email_field`. Default false."},"audience_ids":{"type":"array","items":{"type":"string","maxLength":64},"maxItems":20,"description":"Audiences the contact joins. They must exist in this environment."},"topics":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"description":"Topic keys the contact is opted into."},"double_opt_in":{"type":["boolean","null"],"description":"New contacts confirm their subscription by email first. `null` (default): the environment's marketing settings decide."},"first_name_field":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The field holding the contact's first name. `null`: none."},"last_name_field":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The field holding the contact's last name. `null`: none."},"properties":{"type":"object","additionalProperties":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.\\-[\\]]{0,63}$","description":"The `name` the form's input posts."},"description":"Contact property key → the field whose value it takes."}},"additionalProperties":false,"description":"Turning submissions into contacts. Only the fields given change."},"files":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Accept uploads (`multipart/form-data`). Default false."},"max_files":{"type":"integer","minimum":1,"maximum":10,"description":"Most files per submission. Default 3."},"max_file_bytes":{"type":"integer","minimum":1,"maximum":10485760,"description":"Largest file, in bytes. Default and maximum 10 MB."},"allowed_types":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9.+-]+\\/([a-z0-9.+-]+|\\*)$"},"maxItems":50,"description":"MIME types (`image/*` allowed). Empty: images, PDFs, text and Office."}},"additionalProperties":false,"description":"File uploads. Only the fields given change."},"hosted":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Serve the form as a page at its `hosted_url` (needs `fields`). Default false."},"title":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"The page's heading. `null`: the form's name."},"description":{"type":["string","null"],"maxLength":2000,"description":"Text under the heading. `null`: none."},"submit_label":{"type":["string","null"],"minLength":1,"maxLength":60,"description":"The submit button's label. `null`: the default."},"success_message":{"type":["string","null"],"minLength":1,"maxLength":500,"description":"Shown after a submission. `null`: the default."}},"additionalProperties":false,"description":"The page coss.com can serve for this form. Only the fields given change."}},"additionalProperties":false,"description":"Only the fields given change, within each group too.","examples":[{"spam":{"captcha":"required"},"contacts":{"enabled":true}}]},"DeletedForm":{"type":"object","properties":{"object":{"type":"string","enum":["form"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"form","id":"form_01kd2m8n3p4q5r6s7t8v9w0x1y","deleted":true}]},"FormSubmissionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmission"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[],"has_more":false}]},"FormSubmission":{"type":"object","properties":{"object":{"type":"string","enum":["form_submission"]},"id":{"type":"string","examples":["fsub_01kd2m9a0b1c2d3e4f5g6h7j8k"]},"form_id":{"type":"string","description":"The id of the form it was posted to."},"status":{"type":"string","enum":["pending_confirmation","accepted","held","spam"],"description":"`accepted`: delivered (webhooks, notifications, contacts). `held`: Risk asked for a review. `spam`: refused by Risk, the content check or the honeypot. `pending_confirmation`: waiting for the submitter's email link."},"data":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Field name → value; a field posted several times has an array."},"submitter_email":{"type":["string","null"],"description":"The value of the form's `submitter.email_field`. `null` when it has none."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmissionFile"},"description":"Uploaded files. Download them with the API."},"spam_reason":{"type":["string","null"],"enum":["honeypot","risk_block","risk_review","content",null],"description":"Why it was flagged. `honeypot`: the honeypot field was filled. `risk_block`: Risk blocked it. `risk_review`: Risk asked for a review. `content`: its text passed `content_threshold`. `null`: not flagged."},"risk":{"type":["object","null"],"properties":{"assessment_id":{"type":["string","null"],"description":"The id of Risk's assessment. `null`: none is recorded."},"decision":{"type":["string","null"],"enum":["allow","review","block",null],"description":"Risk's decision. `null`: none is recorded."},"score":{"type":["number","null"],"description":"Risk's score. `null`: none is recorded."}},"required":["assessment_id","decision","score"],"description":"Risk's assessment; `null` when none ran (honeypot)."},"ip":{"type":["string","null"],"description":"The address it was posted from. `null`: unknown."},"user_agent":{"type":["string","null"],"description":"The browser's `User-Agent`. `null`: not sent."},"origin":{"type":["string","null"],"description":"The site it was posted from. `null`: not sent."},"referrer":{"type":["string","null"],"description":"The page it was posted from. `null`: not sent."},"confirmed_at":{"type":["string","null"],"format":"date-time","description":"When the submitter clicked the emailed link. `null`: they haven't, or the form doesn't verify."},"accepted_at":{"type":["string","null"],"format":"date-time","description":"When it became `accepted`. `null`: it hasn't."},"released_at":{"type":["string","null"],"format":"date-time","description":"When it was released from `held` or `spam`. `null`: it wasn't."},"sandbox":{"type":"boolean","description":"Whether it belongs to a sandbox environment."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","form_id","status","data","submitter_email","files","spam_reason","risk","ip","user_agent","origin","referrer","confirmed_at","accepted_at","released_at","sandbox","created_at"],"examples":[{"object":"form_submission","id":"fsub_01kd2m9a0b1c2d3e4f5g6h7j8k","form_id":"form_01kd2m8n3p4q5r6s7t8v9w0x1y","status":"accepted","data":{"name":"Ada Lovelace","email":"ada@example.com","message":"Hello!"},"submitter_email":"ada@example.com","files":[],"spam_reason":null,"risk":{"assessment_id":"rsk_01kd2m9a0b1c2d3e4f5g6h7j8n","decision":"allow","score":0.04},"ip":"203.0.113.7","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)","origin":"https://www.example.com","referrer":"https://www.example.com/contact","confirmed_at":null,"accepted_at":"2026-10-29T10:00:00.000Z","released_at":null,"sandbox":false,"created_at":"2026-10-29T10:00:00.000Z"}]},"DeletedFormSubmission":{"type":"object","properties":{"object":{"type":"string","enum":["form_submission"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"form_submission","id":"fsub_01kd2m9a0b1c2d3e4f5g6h7j8k","deleted":true}]},"SchedulingHost":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.host"]},"id":{"type":"string"},"uid":{"type":["string","null"],"description":"Your own id for this host, unique in the environment, accepted wherever a host id is. `null` when none is set."},"name":{"type":"string","description":"The host's name."},"email":{"type":["string","null"],"description":"Where this host's notifications go. `null` when none is set. Not an identity, and need not be unique."},"phone":{"type":["string","null"],"description":"Where this host's SMS reminders go, in E.164. `null` when none is set."},"calendar_account":{"type":["string","null"],"description":"The mailbox a calendar delegation connects for this host, when it isn't `email`. `null` when none is set."},"time_zone":{"type":"string","description":"The host's IANA time zone. Their schedules default to it, and limits count days and weeks in it."},"locale":{"type":["string","null"],"description":"What this host's notifications are written in. `null`: English."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"What pools filter hosts by, as strings or lists of strings."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingHostLocation"},"description":"This host's own office, meeting link and phone number. An event type's location that leaves its value blank uses them."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"status":{"type":"string","enum":["active","disabled"],"description":"`active`: can be offered. `disabled`: isn't offered, and keeps its existing bookings."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","uid","name","email","phone","calendar_account","time_zone","locale","attributes","locations","metadata","status","created_at","updated_at"],"examples":[{"object":"scheduling.host","id":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","uid":"doctor_482","name":"Dr. Ana Reyes","email":"ana@example.com","phone":null,"calendar_account":null,"time_zone":"America/New_York","locale":null,"attributes":{"licensed_in":["NY","NJ"]},"locations":[{"type":"in_person","address":"12 Main St, New York, NY"}],"metadata":{},"status":"active","created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"SchedulingHostLocation":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["link"],"description":"A meeting link of the host's own."},"url":{"type":"string","maxLength":2000,"format":"uri","description":"The link, which must be `https`."}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["phone"],"description":"A phone number of the host's own."},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"The number, in E.164 format."}},"required":["type","number"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["in_person"],"description":"The host's own office."},"address":{"type":"string","minLength":1,"maxLength":500,"description":"The address. It can't contain a link."}},"required":["type","address"],"additionalProperties":false}],"description":"Where this host meets. A host has at most one of each type."},"CreateHostRequest":{"type":"object","properties":{"uid":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for this host, unique in the environment."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"The host's name."},"email":{"type":"string","maxLength":320,"format":"email","description":"Where this host's notifications go. Not an identity, and need not be unique."},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Where this host's SMS reminders go, in E.164."},"calendar_account":{"type":["string","null"],"maxLength":320,"format":"email","description":"The mailbox a calendar delegation connects for this host, when it isn't `email` or the delegation doesn't match on email. In Microsoft 365, their user principal name."},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"An IANA time zone name.","examples":["America/New_York"]},"locale":{"type":["string","null"],"minLength":2,"maxLength":35,"description":"What this host's notifications are written in, such as `de`. Default: English. `null` removes it."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"What pools filter hosts by, such as `{ \"licensed_in\": [\"CA\", \"NY\"], \"language\": \"es\" }`."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingHostLocation"},"maxItems":3,"description":"This host's own office, meeting link and phone number. An event type's location that leaves its value blank uses them."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs. Don't put sensitive data here."}},"required":["name","time_zone"],"additionalProperties":false,"examples":[{"uid":"doctor_482","name":"Dr. Ana Reyes","email":"ana@example.com","time_zone":"America/New_York","attributes":{"licensed_in":["NY","NJ"]},"locations":[{"type":"in_person","address":"12 Main St, New York, NY"}]}]},"SchedulingHostList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingHost"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.host","id":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","uid":"doctor_482","name":"Dr. Ana Reyes","email":"ana@example.com","phone":null,"calendar_account":null,"time_zone":"America/New_York","locale":null,"attributes":{"licensed_in":["NY","NJ"]},"locations":[{"type":"in_person","address":"12 Main St, New York, NY"}],"metadata":{},"status":"active","created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"UpdateHostRequest":{"type":"object","properties":{"uid":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Your own id for this host, unique in the environment."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"The host's name."},"email":{"type":["string","null"],"maxLength":320,"format":"email","description":"Where this host's notifications go. `null` removes it."},"phone":{"type":["string","null"],"pattern":"^\\+[1-9]\\d{6,14}$","description":"Where this host's SMS reminders go, in E.164. `null` removes it."},"calendar_account":{"type":["string","null"],"maxLength":320,"format":"email","description":"Moves the host's delegated calendar to this mailbox. Refused while they have upcoming bookings or holds."},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"An IANA time zone name.","examples":["America/New_York"]},"locale":{"type":["string","null"],"minLength":2,"maxLength":35,"description":"What this host's notifications are written in, such as `de`. Default: English. `null` removes it."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"What pools filter hosts by, such as `{ \"licensed_in\": [\"CA\", \"NY\"], \"language\": \"es\" }`."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingHostLocation"},"maxItems":3,"description":"Replaces this host's own locations. Existing bookings keep the location they have."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs. Don't put sensitive data here."},"status":{"type":"string","enum":["active","disabled"],"description":"A `disabled` host isn't offered. Its existing bookings stay."}},"additionalProperties":false,"examples":[{"status":"disabled"}]},"DeletedSchedulingHost":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.host"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"scheduling.host","id":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","deleted":true}]},"SchedulingBooking":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.booking"]},"id":{"type":"string"},"event_type":{"type":"string","description":"The id of the booked event type."},"status":{"type":"string","enum":["held","pending_approval","confirmed","cancelled","declined"],"description":"`held`: a hold keeping the slot until `hold_expires_at`, uncharged and known to nobody. `pending_approval`: holds the time until approved, declined or `approval_expires_at`. `confirmed`: booked. `cancelled`: cancelled, or a hold released or expired. `declined`: refused, or its approval deadline passed."},"title":{"type":"string","description":"The event type's title when this was booked."},"start":{"type":"string","description":"When the booking starts."},"end":{"type":"string","description":"When the booking ends, without buffers."},"hosts":{"type":"array","items":{"type":"string"},"description":"The ids of the hosts taking it."},"attendees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["attendee","guest"],"description":"`attendee` booked it and comes first; a `guest` was added by them."},"uid":{"type":["string","null"],"description":"Your own id for this person. `null` when none was given."},"name":{"type":["string","null"],"description":"`null` when not given, or after their details are erased."},"email":{"type":["string","null"],"description":"`null` when not given, or after their details are erased."},"phone":{"type":["string","null"],"description":"`null` when not given, or after their details are erased."},"time_zone":{"type":"string","description":"Their IANA time zone."},"locale":{"type":["string","null"],"description":"Their locale. `null` when not given."},"answers":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Only when retrieving one booking."}},"required":["id","role","uid","name","email","phone","time_zone","locale"]},"description":"Who's booked: the attendee first, then any guests they added. A group session's seat is its own booking."},"location":{"$ref":"#/components/schemas/SchedulingLocation"},"hold_expires_at":{"type":["string","null"],"description":"When a `held` booking gives up its slot. `null` otherwise."},"approval_expires_at":{"type":["string","null"],"description":"When a `pending_approval` booking is declined if nobody decides. `null` otherwise."},"series":{"type":["string","null"],"description":"The id of the series it belongs to. `null`: not part of one."},"series_index":{"type":["number","null"],"description":"Its place in the series, from 0. `null`: not part of one."},"group_session":{"type":["string","null"],"description":"The id of the group session whose seat this is. `null`: not a seat."},"calendar_unverified":{"type":"boolean","description":"Reserved for flagging a booking made on last known calendar data. Nothing sets it yet, so it's always `false`."},"external_conflict_at":{"type":["string","null"],"description":"When something else landed on this time in the host's calendar, or the host changed the event. The booking stands. `null`: no conflict known."},"no_show_at":{"type":["string","null"],"description":"When the attendee was marked as a no-show. `null`: not marked."},"cancelled_at":{"type":["string","null"],"description":"When it was cancelled. `null`: not cancelled."},"cancelled_by":{"type":["string","null"],"enum":["api_key","user","host_session","booker_session","manage_session","manager_session","system",null],"description":"Who cancelled it: `api_key`, `user` (the dashboard), `host_session`, `booker_session`, `manage_session` (the attendee's link) or `system`. `null`: not cancelled, or cancelled before this was recorded."},"cancellation_reason":{"type":["string","null"],"description":"Why, if they said. Only when retrieving one booking. It's erased with the attendee's details, and it's never in webhooks, logs or emails."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","event_type","status","title","start","end","hosts","attendees","location","hold_expires_at","approval_expires_at","series","series_index","group_session","calendar_unverified","external_conflict_at","no_show_at","cancelled_at","cancelled_by","metadata","created_at","updated_at"],"examples":[{"object":"scheduling.booking","id":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"confirmed","title":"Initial consultation","start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z","hosts":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"],"attendees":[{"id":"attn_01kd2m9a0b1c2d3e4f5g6h7j8m","role":"attendee","uid":"patient_77","name":"Sam Lee","email":"sam@example.com","phone":null,"time_zone":"UTC","locale":null}],"location":null,"hold_expires_at":null,"approval_expires_at":null,"series":null,"series_index":null,"group_session":null,"calendar_unverified":false,"external_conflict_at":null,"no_show_at":null,"cancelled_at":null,"cancelled_by":null,"metadata":{},"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"SchedulingLocation":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["link"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting link. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["phone"]},"number":{"type":["string","null"],"maxLength":32,"default":null,"description":"The phone number to call. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["in_person"]},"address":{"type":["string","null"],"maxLength":500,"default":null,"description":"The address to meet at. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["google_meet"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["microsoft_teams"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["zoom"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting's link, once it's created on the host's Zoom account."}},"required":["type"],"additionalProperties":false},{"type":"null"}],"description":"Where a booking meets. `link`, `phone` and `in_person` carry their details, and on an event type, left blank, use the booked host's own if they have one; `google_meet`, `microsoft_teams` and `zoom` get a meeting made on the host's connected account."},"ReassignSchedulingBookingRequest":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"from_host":{"type":"string","description":"The host leaving, by id or uid. Needed when it could be several."},"to_host":{"type":"string","description":"The host taking over, by id or uid. Or set `auto`."},"auto":{"type":"boolean","description":"Let coss.com pick, as a pool would: the fairest who's free and fits what the booking was routed with."},"preferred_hosts":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"With `auto`: try these first, in order."}},"additionalProperties":false},"minItems":1,"maxItems":10,"description":"A session or a one-on-one has one. A collective can change several."},"reason_code":{"type":"string","enum":["host_unavailable","out_of_office","workload","customer_request","offboarding","other"]},"note":{"type":"string","maxLength":500,"description":"Why, in your words: required with an override of someone's availability. Encrypted, and only in the booking's history."},"overrides":{"type":"array","items":{"type":"string","enum":["any_host","out_of_office","outside_availability","host_busy","limit_reached","calendar_unverified"]},"maxItems":6,"description":"Go ahead anyway: `any_host` for someone who doesn't take this event type, and the rest for what a candidate's `reason` said. A host who already has something at this time can never be overridden."},"notify":{"type":"object","properties":{"attendee":{"type":"boolean","description":"Tell the attendee. Default: true."}},"additionalProperties":false}},"required":["changes","reason_code"],"additionalProperties":false,"examples":[{"changes":[{"to_host":"doctor_518"}],"reason_code":"out_of_office"}]},"SchedulingReassignCandidateList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingReassignCandidate"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.reassign_candidate","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","uid":"doctor_518","name":"Dr. Priya Raman","member":true,"available":true,"reason":null,"reasons":[],"load":4,"rank":1,"meeting_provider_missing":false}],"has_more":false}]},"SchedulingReassignCandidate":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.reassign_candidate"]},"host":{"type":"string"},"uid":{"type":["string","null"]},"name":{"type":"string"},"member":{"type":"boolean","description":"Takes this event type, and fits what the booking was routed with. Otherwise it needs `any_host`."},"available":{"type":"boolean"},"reason":{"type":["string","null"],"description":"Why they aren't available, the first of `reasons`."},"reasons":{"type":"array","items":{"type":"string"},"description":"Everything in the way, each needing its override. `already_claimed` can't be overridden."},"load":{"type":"number","description":"Their live bookings in the week from this one."},"rank":{"type":["number","null"],"description":"Their place in who a pool would pick next, from 1. Null for a non-member."},"meeting_provider_missing":{"type":"boolean","description":"They haven't connected what this booking's meeting needs, so it'd have none."}},"required":["object","host","uid","name","member","available","reason","reasons","load","rank","meeting_provider_missing"],"examples":[{"object":"scheduling.reassign_candidate","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","uid":"doctor_518","name":"Dr. Priya Raman","member":true,"available":true,"reason":null,"reasons":[],"load":4,"rank":1,"meeting_provider_missing":false}]},"SchedulingReassignmentPreview":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.reassignment_preview"]},"items":{"type":"array","items":{"type":"object","properties":{"booking":{"type":"string"},"event_type":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["held","pending_approval","confirmed","cancelled","declined"]},"start":{"type":"string"},"end":{"type":"string"},"series":{"type":["string","null"]},"group_session":{"type":["string","null"]},"from_host":{"type":["string","null"]},"to_host":{"type":["string","null"],"description":"Null when nobody could take it."},"reason":{"type":["string","null"],"description":"Why it would stay where it is."}},"required":["booking","event_type","title","status","start","end","series","group_session","from_host","to_host","reason"]}},"truncated":{"type":"boolean","description":"There are more than a preview covers."}},"required":["object","items","truncated"],"examples":[{"object":"scheduling.reassignment_preview","items":[{"booking":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","title":"Consultation","status":"confirmed","start":"2027-08-03T15:00:00.000Z","end":"2027-08-03T15:30:00.000Z","series":null,"group_session":null,"from_host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","to_host":"host_01kd2m9a0b1c2d3e4f5g6h7j8n","reason":null}],"truncated":false}]},"PreviewSchedulingReassignmentRequest":{"type":"object","properties":{"selection":{"$ref":"#/components/schemas/SchedulingReassignmentSelection"},"strategy":{"$ref":"#/components/schemas/SchedulingReassignmentStrategy"},"overrides":{"type":"array","items":{"type":"string","enum":["any_host","out_of_office","outside_availability","host_busy","limit_reached","calendar_unverified"]},"maxItems":6}},"required":["selection"],"additionalProperties":false,"examples":[{"selection":{"host":"doctor_482","start_before":"2027-08-14T00:00:00.000Z"},"strategy":{"preferred_hosts":["doctor_518"]}}]},"SchedulingReassignmentSelection":{"type":"object","properties":{"host":{"type":"string","description":"This host's bookings, by id or uid."},"out_of_office":{"type":"string","description":"The bookings that fall in this entry."},"booking_ids":{"type":"array","items":{"type":"string"},"maxItems":5000},"series":{"type":"string","description":"A series' occurrences still to come."},"start_after":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"start_before":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"event_types":{"type":"array","items":{"type":"string"},"maxItems":100},"external_conflict":{"type":"boolean","description":"Only those with something else on the host's calendar at that time."}},"additionalProperties":false},"SchedulingReassignmentStrategy":{"type":"object","properties":{"to_host":{"type":"string","description":"Give them all to this host."},"preferred_hosts":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Try these first, in order."},"otherwise":{"type":"string","enum":["auto","leave"],"description":"After `preferred_hosts`: `auto` picks the fairest who's free, `leave` keeps it where it is."},"assignments":{"type":"array","items":{"type":"object","properties":{"booking":{"type":"string"},"to_host":{"type":"string"},"from_host":{"type":"string"}},"required":["booking","to_host"],"additionalProperties":false},"maxItems":5000,"description":"Who each goes to: a preview, with your changes."}},"default":{},"additionalProperties":false},"SchedulingReassignment":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.reassignment"]},"id":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","cancelled"]},"reason_code":{"type":"string","enum":["host_unavailable","out_of_office","workload","customer_request","offboarding","other"]},"out_of_office":{"type":["string","null"]},"undo_of":{"type":["string","null"]},"counts":{"type":"object","properties":{"total":{"type":"number"},"pending":{"type":"number"},"reassigned":{"type":"number"},"skipped":{"type":"number","description":"They'd moved on since it was selected."},"no_candidate":{"type":"number","description":"Nobody could take them: they stayed."},"failed":{"type":"number"},"cancelled":{"type":"number"}},"required":["total","pending","reassigned","skipped","no_candidate","failed","cancelled"]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"finished_at":{"type":["string","null"]}},"required":["object","id","status","reason_code","out_of_office","undo_of","counts","created_at","started_at","finished_at"],"examples":[{"object":"scheduling.reassignment","id":"reasn_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"completed","reason_code":"out_of_office","out_of_office":"ooo_01kd2m9a0b1c2d3e4f5g6h7j8m","undo_of":null,"counts":{"total":12,"pending":0,"reassigned":11,"skipped":0,"no_candidate":1,"failed":0,"cancelled":0},"created_at":"2027-01-01T10:00:00.000Z","started_at":"2027-01-01T10:00:01.000Z","finished_at":"2027-01-01T10:00:09.000Z"}]},"CreateSchedulingReassignmentRequest":{"type":"object","properties":{"selection":{"$ref":"#/components/schemas/SchedulingReassignmentSelection"},"strategy":{"$ref":"#/components/schemas/SchedulingReassignmentStrategy"},"reason_code":{"type":"string","enum":["host_unavailable","out_of_office","workload","customer_request","offboarding","other"]},"note":{"type":"string","maxLength":500,"description":"Why, in your words: required with an override of someone's availability."},"overrides":{"type":"array","items":{"type":"string","enum":["any_host","out_of_office","outside_availability","host_busy","limit_reached","calendar_unverified"]},"maxItems":6},"notify":{"type":"object","properties":{"attendees":{"type":"boolean","description":"Tell attendees. Default: true."},"hosts":{"type":"string","enum":["digest","each","none"],"description":"`digest` (the default) sends each host one email for the run."}},"additionalProperties":false}},"required":["selection","reason_code"],"additionalProperties":false,"examples":[{"selection":{"out_of_office":"ooo_01kd2m9a0b1c2d3e4f5g6h7j8m"},"strategy":{"preferred_hosts":["doctor_518"]},"reason_code":"out_of_office"}]},"SchedulingReassignmentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingReassignment"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.reassignment","id":"reasn_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"completed","reason_code":"out_of_office","out_of_office":"ooo_01kd2m9a0b1c2d3e4f5g6h7j8m","undo_of":null,"counts":{"total":12,"pending":0,"reassigned":11,"skipped":0,"no_candidate":1,"failed":0,"cancelled":0},"created_at":"2027-01-01T10:00:00.000Z","started_at":"2027-01-01T10:00:01.000Z","finished_at":"2027-01-01T10:00:09.000Z"}],"has_more":false}]},"SchedulingReassignmentItemList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingReassignmentItem"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.reassignment_item","id":"reasi_01kd2m9a0b1c2d3e4f5g6h7j8m","booking":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","from_host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","to_host":"host_01kd2m9a0b1c2d3e4f5g6h7j8n","outcome":"reassigned","error_code":null}],"has_more":false}]},"SchedulingReassignmentItem":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.reassignment_item"]},"id":{"type":"string"},"booking":{"type":"string"},"from_host":{"type":["string","null"]},"to_host":{"type":["string","null"]},"outcome":{"type":"string","enum":["pending","reassigned","skipped_changed","no_candidate","failed","cancelled"]},"error_code":{"type":["string","null"]}},"required":["object","id","booking","from_host","to_host","outcome","error_code"],"examples":[{"object":"scheduling.reassignment_item","id":"reasi_01kd2m9a0b1c2d3e4f5g6h7j8m","booking":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","from_host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","to_host":"host_01kd2m9a0b1c2d3e4f5g6h7j8n","outcome":"reassigned","error_code":null}]},"UndoSchedulingReassignmentRequest":{"type":"object","properties":{"reason_code":{"type":"string","enum":["host_unavailable","out_of_office","workload","customer_request","offboarding","other"]},"note":{"type":"string","maxLength":500},"overrides":{"type":"array","items":{"type":"string","enum":["any_host","out_of_office","outside_availability","host_busy","limit_reached","calendar_unverified"]},"maxItems":6},"notify":{"type":"object","properties":{"attendees":{"type":"boolean","description":"Tell attendees. Default: true."},"hosts":{"type":"string","enum":["digest","each","none"],"description":"`digest` (the default) sends each host one email for the run."}},"additionalProperties":false}},"additionalProperties":false,"examples":[{"reason_code":"other"}]},"SchedulingHolidayCalendar":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.holiday_calendar"]},"id":{"type":"string"},"name":{"type":"string"},"source":{"type":"string","enum":["country","ics"]},"country":{"type":["string","null"]},"hosts":{"type":["array","null"],"items":{"type":"string"}},"host_filter":{"type":["object","null"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"regions":{"type":["array","null"],"items":{"type":"string"}},"delegates":{"type":"array","items":{"type":"string"}},"existing_bookings":{"type":"string","enum":["leave","reassign"]},"last_read_at":{"type":["string","null"]},"last_error":{"type":["string","null"],"description":"Why its feed couldn't be read."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","name","source","country","hosts","host_filter","regions","delegates","existing_bookings","last_read_at","last_error","created_at","updated_at"],"examples":[{"object":"scheduling.holiday_calendar","id":"hcal_01kd2m9a0b1c2d3e4f5g6h7j8m","name":"UK team","source":"country","country":"GB","hosts":null,"host_filter":{"team":"london"},"regions":["England"],"delegates":[],"existing_bookings":"leave","last_read_at":"2027-01-01T10:00:00.000Z","last_error":null,"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"CreateSchedulingHolidayCalendarRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"country":{"type":"string","description":"A code from the list of holiday calendars, such as `GB`."},"ics_url":{"type":"string","maxLength":2000,"format":"uri","description":"Your own feed, https or webcal, read in live environments. Stored encrypted."},"hosts":{"type":"array","items":{"type":"string"},"maxItems":1000,"description":"These hosts, by id or uid."},"host_filter":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Everyone matching these attributes, asked again at every sync."},"regions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"description":"Which regional holidays apply, matched against how the calendar names them, such as `England`. Without this, all of them do; empty, only nationwide ones."},"delegates":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Who can be booked in their place on those days, by id or uid, in order."},"existing_bookings":{"type":"string","enum":["leave","reassign"],"description":"What happens to bookings already on a holiday. `leave` (the default) only reports them. `reassign` moves them."}},"required":["name"],"additionalProperties":false,"examples":[{"name":"UK team","country":"GB","host_filter":{"team":"london"}}]},"SchedulingHolidayCalendarList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingHolidayCalendar"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass this position as after for the next page."}},"required":["object","data","has_more","next_cursor"],"examples":[{"object":"list","data":[{"object":"scheduling.holiday_calendar","id":"hcal_01kd2m9a0b1c2d3e4f5g6h7j8m","name":"UK team","source":"country","country":"GB","hosts":null,"host_filter":{"team":"london"},"regions":["England"],"delegates":[],"existing_bookings":"leave","last_read_at":"2027-01-01T10:00:00.000Z","last_error":null,"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false,"next_cursor":null}]},"SchedulingHolidayList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"name":{"type":"string"},"region":{"type":["string","null"]}},"required":["date","name","region"]}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"date":"2027-12-25","name":"Christmas Day","region":null}],"has_more":false}]},"UpdateSchedulingHolidayCalendarRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"hosts":{"type":"array","items":{"type":"string"},"maxItems":1000,"description":"These hosts, by id or uid."},"host_filter":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Everyone matching these attributes, asked again at every sync."},"regions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"description":"Which regional holidays apply, matched against how the calendar names them, such as `England`. Without this, all of them do; empty, only nationwide ones."},"delegates":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Who can be booked in their place on those days, by id or uid, in order."},"existing_bookings":{"type":"string","enum":["leave","reassign"],"description":"What happens to bookings already on a holiday. `leave` (the default) only reports them. `reassign` moves them."}},"additionalProperties":false,"examples":[{"host_filter":{"team":"london"}}]},"DeletedSchedulingHolidayCalendar":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"examples":[{"id":"hcal_01kd2m9a0b1c2d3e4f5g6h7j8m","deleted":true}]},"SchedulingOutOfOfficeList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingOutOfOffice"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.out_of_office","id":"ooo_01kd2m9a0b1c2d3e4f5g6h7j8m","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","start":"2027-08-02T04:00:00.000Z","end":"2027-08-14T04:00:00.000Z","all_day":{"start_date":"2027-08-02","end_date":"2027-08-13","time_zone":"America/New_York"},"reason":"vacation","notes":null,"public_message":"Back on the 16th.","show_on_calendar":true,"delegates":["host_01kd2m9a0b1c2d3e4f5g6h7j8n"],"existing_bookings":"leave","external_id":null,"group":null,"source":"api","created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"SchedulingOutOfOffice":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.out_of_office"]},"id":{"type":"string"},"host":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"all_day":{"type":["object","null"],"properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"time_zone":{"type":"string"}},"required":["start_date","end_date","time_zone"],"description":"How it was given, when it was as whole dates."},"reason":{"type":"string"},"notes":{"type":["string","null"]},"public_message":{"type":["string","null"]},"show_on_calendar":{"type":"boolean"},"delegates":{"type":"array","items":{"type":"string"},"description":"Who can be booked in their place."},"existing_bookings":{"type":"string","enum":["leave","reassign"]},"external_id":{"type":["string","null"]},"group":{"type":["string","null"],"description":"Shared by the entries one request made for several hosts."},"source":{"type":"string","enum":["api","host","manager","dashboard","holiday"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","host","start","end","all_day","reason","notes","public_message","show_on_calendar","delegates","existing_bookings","external_id","group","source","created_at","updated_at"],"examples":[{"object":"scheduling.out_of_office","id":"ooo_01kd2m9a0b1c2d3e4f5g6h7j8m","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","start":"2027-08-02T04:00:00.000Z","end":"2027-08-14T04:00:00.000Z","all_day":{"start_date":"2027-08-02","end_date":"2027-08-13","time_zone":"America/New_York"},"reason":"vacation","notes":null,"public_message":"Back on the 16th.","show_on_calendar":true,"delegates":["host_01kd2m9a0b1c2d3e4f5g6h7j8n"],"existing_bookings":"leave","external_id":null,"group":null,"source":"api","created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"CreateSchedulingOutOfOfficeRequest":{"type":"object","properties":{"host":{"type":"string","description":"One host, by id or uid."},"hosts":{"type":"array","items":{"type":"string"},"maxItems":500,"description":"Several hosts, by id or uid. Each gets an entry of their own."},"host_filter":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Every active host matching these attributes right now. A host added later isn't covered."},"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"end":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The first whole day away. Use instead of `start` and `end`.","examples":["2027-08-02"]},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last whole day away, which is included.","examples":["2027-08-13"]},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"What the dates mean in. Default: the host's zone when this is made.","examples":["America/New_York"]},"delegates":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Who can be booked in this host's place during it, by id or uid, in the order to try them. They still have to fit how a booking's routed."},"reason":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$","description":"One of `unspecified`, `vacation`, `travel`, `sick`, `public_holiday`, `parental_leave`, `training` and `other`, or a key from the settings' `out_of_office_reasons`. Only people who manage this host see it: never bookers, webhooks or calendars.","examples":["vacation"]},"notes":{"type":"string","maxLength":2000,"description":"For people who manage this host. Encrypted, and never shown to a booker."},"public_message":{"type":"string","maxLength":300,"description":"Shown to bookers while this host is away. Can't contain a link.","examples":["Back on the 16th. Priya is seeing my patients until then."]},"show_on_calendar":{"type":"boolean","description":"Put a private \"Out of office\" event on the host's calendar. Default: true."},"existing_bookings":{"type":"string","enum":["leave","reassign"],"description":"What happens to bookings already in the way. `leave` (the default) only reports them. `reassign` moves them, and any nobody can take stay where they are."},"reassign":{"type":"object","properties":{"to_host":{"type":"string","description":"Give them all to this host."},"preferred_hosts":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Try these first, in order."},"otherwise":{"type":"string","enum":["auto","leave"],"description":"After `preferred_hosts`: `auto` picks the fairest who's free (the default), `leave` keeps it where it is."}},"additionalProperties":false,"description":"With `existing_bookings: reassign`: who they go to. Default: the fairest who's free."},"external_id":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for this entry, unique in the environment. Needs one host."}},"additionalProperties":false,"examples":[{"host":"doctor_482","start_date":"2027-08-02","end_date":"2027-08-13","reason":"vacation","public_message":"Back on the 16th."}]},"UpdateSchedulingOutOfOfficeRequest":{"type":"object","properties":{"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"end":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The first whole day away. Use instead of `start` and `end`.","examples":["2027-08-02"]},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last whole day away, which is included.","examples":["2027-08-13"]},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"What the dates mean in. Default: the host's zone when this is made.","examples":["America/New_York"]},"reason":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$","description":"One of `unspecified`, `vacation`, `travel`, `sick`, `public_holiday`, `parental_leave`, `training` and `other`, or a key from the settings' `out_of_office_reasons`. Only people who manage this host see it: never bookers, webhooks or calendars.","examples":["vacation"]},"notes":{"type":["string","null"],"maxLength":2000},"public_message":{"type":["string","null"],"maxLength":300},"show_on_calendar":{"type":"boolean"},"delegates":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Who can be booked in this host's place during it, by id or uid, in the order to try them. They still have to fit how a booking's routed."},"existing_bookings":{"type":"string","enum":["leave","reassign"],"description":"What happens to bookings already in the way. `leave` (the default) only reports them. `reassign` moves them, and any nobody can take stay where they are."},"reassign":{"type":"object","properties":{"to_host":{"type":"string","description":"Give them all to this host."},"preferred_hosts":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Try these first, in order."},"otherwise":{"type":"string","enum":["auto","leave"],"description":"After `preferred_hosts`: `auto` picks the fairest who's free (the default), `leave` keeps it where it is."}},"additionalProperties":false,"description":"With `existing_bookings: reassign`: who they go to. Default: the fairest who's free."}},"additionalProperties":false,"examples":[{"end_date":"2027-08-20"}]},"PutSchedulingOutOfOfficeRequest":{"type":"object","properties":{"host":{"type":"string","description":"The host, by id or uid."},"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"end":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The first whole day away. Use instead of `start` and `end`.","examples":["2027-08-02"]},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last whole day away, which is included.","examples":["2027-08-13"]},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"What the dates mean in. Default: the host's zone when this is made.","examples":["America/New_York"]},"delegates":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Who can be booked in this host's place during it, by id or uid, in the order to try them. They still have to fit how a booking's routed."},"reason":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$","description":"One of `unspecified`, `vacation`, `travel`, `sick`, `public_holiday`, `parental_leave`, `training` and `other`, or a key from the settings' `out_of_office_reasons`. Only people who manage this host see it: never bookers, webhooks or calendars.","examples":["vacation"]},"notes":{"type":"string","maxLength":2000,"description":"For people who manage this host. Encrypted, and never shown to a booker."},"public_message":{"type":"string","maxLength":300,"description":"Shown to bookers while this host is away. Can't contain a link.","examples":["Back on the 16th. Priya is seeing my patients until then."]},"show_on_calendar":{"type":"boolean","description":"Put a private \"Out of office\" event on the host's calendar. Default: true."},"existing_bookings":{"type":"string","enum":["leave","reassign"],"description":"What happens to bookings already in the way. `leave` (the default) only reports them. `reassign` moves them, and any nobody can take stay where they are."},"reassign":{"type":"object","properties":{"to_host":{"type":"string","description":"Give them all to this host."},"preferred_hosts":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Try these first, in order."},"otherwise":{"type":"string","enum":["auto","leave"],"description":"After `preferred_hosts`: `auto` picks the fairest who's free (the default), `leave` keeps it where it is."}},"additionalProperties":false,"description":"With `existing_bookings: reassign`: who they go to. Default: the fairest who's free."}},"required":["host"],"additionalProperties":false,"examples":[{"host":"doctor_482","start_date":"2027-08-02","end_date":"2027-08-13","reason":"vacation"}]},"DeletedSchedulingOutOfOffice":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.out_of_office"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"scheduling.out_of_office","id":"ooo_01kd2m9a0b1c2d3e4f5g6h7j8m","deleted":true}]},"SchedulingOutOfOfficeConflictList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingOutOfOfficeConflict"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.out_of_office_conflict","booking":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","title":"Consultation","status":"confirmed","start":"2027-08-03T15:00:00.000Z","end":"2027-08-03T15:30:00.000Z","series":null,"group_session":null}],"has_more":false}]},"SchedulingOutOfOfficeConflict":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.out_of_office_conflict"]},"booking":{"type":"string"},"event_type":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["held","pending_approval","confirmed","cancelled","declined"]},"start":{"type":"string"},"end":{"type":"string"},"series":{"type":["string","null"]},"group_session":{"type":["string","null"]}},"required":["object","booking","event_type","title","status","start","end","series","group_session"],"examples":[{"object":"scheduling.out_of_office_conflict","booking":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","title":"Consultation","status":"confirmed","start":"2027-08-03T15:00:00.000Z","end":"2027-08-03T15:30:00.000Z","series":null,"group_session":null}]},"SchedulingSchedule":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.schedule"]},"id":{"type":"string"},"host":{"type":"string","description":"The id of the host this schedule belongs to."},"name":{"type":"string","description":"A label for the schedule. `Default` when none was given."},"time_zone":{"type":"string","description":"The IANA time zone its rules and overrides are local to."},"is_default":{"type":"boolean","description":"Whether this is the host's default schedule, used by event types that don't name one. A host's first schedule always is."},"rules":{"type":"array","items":{"type":"object","properties":{"days":{"type":"array","items":{"type":"number"},"description":"Weekdays, with Sunday as 0."},"start":{"type":"string","description":"Local start time, `HH:MM`."},"end":{"type":"string","description":"Local end time, `HH:MM`. `24:00` is the end of the day."}},"required":["days","start","end"]},"description":"Weekly hours in local time, unchanged across daylight saving."},"overrides":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"The local date, `YYYY-MM-DD`."},"ranges":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"Local start time, `HH:MM`."},"end":{"type":"string","description":"Local end time, `HH:MM`. `24:00` is the end of the day."}},"required":["start","end"]},"description":"That day's hours. Empty means unavailable all day."}},"required":["date","ranges"]},"description":"Dates whose hours replace the weekly rules."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","host","name","time_zone","is_default","rules","overrides","created_at","updated_at"],"examples":[{"object":"scheduling.schedule","id":"sched_01kd2m9a0b1c2d3e4f5g6h7j8m","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","name":"Clinic hours","time_zone":"America/New_York","is_default":true,"rules":[{"days":[1,2,3,4,5],"start":"09:00","end":"17:00"}],"overrides":[{"date":"2027-12-24","ranges":[]}],"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"UpsertScheduleRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"A label for the schedule. Default on creation: `Default`."},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"Default: the host's.","examples":["America/New_York"]},"is_default":{"type":"boolean","description":"`true` makes this the host's default schedule, in place of the current one. A host's first schedule is their default anyway."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingWeeklyRule"},"maxItems":50,"description":"Weekly hours in local time. A range can't cross midnight: use two."},"overrides":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingScheduleOverride"},"maxItems":366,"description":"Replaces the schedule's overrides when given."}},"required":["rules"],"additionalProperties":false,"examples":[{"name":"Clinic hours","rules":[{"days":[1,2,3,4,5],"start":"09:00","end":"17:00"}],"overrides":[{"date":"2027-12-24","ranges":[]}]}]},"SchedulingWeeklyRule":{"type":"object","properties":{"days":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"minItems":1,"maxItems":7,"description":"Weekdays, with Sunday as 0."},"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$|^24:00$","description":"A local time, `HH:MM`. `24:00` is the end of the day."},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$|^24:00$","description":"A local time, `HH:MM`. `24:00` is the end of the day."}},"required":["days","start","end"],"additionalProperties":false},"SchedulingScheduleOverride":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"A local date in the schedule's time zone.","examples":["2027-12-24"]},"ranges":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$|^24:00$","description":"A local time, `HH:MM`. `24:00` is the end of the day."},"end":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$|^24:00$","description":"A local time, `HH:MM`. `24:00` is the end of the day."}},"required":["start","end"],"additionalProperties":false},"maxItems":10,"description":"Replaces the weekly rules that day. Empty means unavailable all day."}},"required":["date","ranges"],"additionalProperties":false},"SchedulingScheduleList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingSchedule"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.schedule","id":"sched_01kd2m9a0b1c2d3e4f5g6h7j8m","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","name":"Clinic hours","time_zone":"America/New_York","is_default":true,"rules":[{"days":[1,2,3,4,5],"start":"09:00","end":"17:00"}],"overrides":[{"date":"2027-12-24","ranges":[]}],"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"DeletedSchedulingSchedule":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.schedule"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"scheduling.schedule","id":"sched_01kd2m9a0b1c2d3e4f5g6h7j8m","deleted":true}]},"SchedulingEventType":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.event_type"]},"id":{"type":"string"},"uid":{"type":["string","null"],"description":"Your own id for this event type, accepted wherever its id is. `null` when none is set."},"description":{"type":["string","null"],"description":"Plain text shown on hosted booking pages. `null` when there's none."},"title":{"type":"string","description":"Shown to attendees and in emails. Host calendars show it only with `host_calendar_details: full`."},"kind":{"type":"string","enum":["one_on_one","pool","collective","group"],"description":"Who a booking needs. `one_on_one`: one host. `pool`: any one of its hosts. `collective`: every `required` host, plus at most one `member`. `group`: one host, with attendees taking seats up to `capacity`."},"status":{"type":"string","enum":["active","archived"],"description":"`active`: can be booked. `archived`: new bookings answer `not_found`; existing ones stay."},"duration_minutes":{"type":"number","description":"How long a booking lasts by default, in minutes."},"duration_options":{"type":"array","items":{"type":"number"},"description":"Other lengths an attendee may choose, in minutes. Empty: only `duration_minutes`."},"step_minutes":{"type":"number","description":"How far apart slots start, in minutes."},"grid_time_zone":{"type":["string","null"],"description":"The zone slots align in. `null`: each host's own."},"buffer_before_minutes":{"type":"number","description":"Minutes kept free before each booking."},"buffer_after_minutes":{"type":"number","description":"Minutes kept free after each booking."},"min_notice_minutes":{"type":"number","description":"Slots starting sooner than this many minutes from now aren't offered."},"booking_window":{"$ref":"#/components/schemas/SchedulingBookingWindow"},"limits":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingLimit"},"description":"Caps on bookings per day or week."},"capacity":{"type":["number","null"],"description":"Attendees per session of a `group` event type. `null` for every other kind."},"requires_approval":{"type":"boolean","description":"Whether bookings start as `pending_approval`, holding the time until approved or declined."},"reassignment_enabled":{"type":"boolean","description":"Whether bookings of this event type can go to another host."},"approval_ttl_minutes":{"type":"number","description":"How long a booking can wait for approval before it's declined, in minutes."},"hold_ttl_seconds":{"type":"number","description":"How long a hold keeps its slot, in seconds."},"cancel_notice_minutes":{"type":"number","description":"Attendees can't cancel closer to the start than this. API keys can."},"reschedule_notice_minutes":{"type":"number","description":"Attendees can't reschedule closer to the start than this. API keys can."},"max_guests":{"type":"number","description":"How many people an attendee can add to a booking. Not on `group`."},"max_active_bookings_per_attendee":{"type":["number","null"],"description":"How many upcoming bookings of this event type one person can have at a time. `null`: no limit."},"host_calendar_details":{"type":"string","enum":["neutral","full"],"description":"What hosts' calendars say about a booking. `neutral`: a private event titled \"Appointment\". `full`: a private event with this title and the attendee's and guests' details."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingQuestion"},"description":"What attendees are asked when booking."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingLocation"},"description":"Where bookings can meet. A browser only chooses among these."},"host_filter":{"type":["object","null"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Pool members also include active hosts matching all of these attributes. `null`: only `hosts`."},"notifications":{"type":["object","null"],"additionalProperties":{"type":"object","properties":{"email_attendee":{"type":"boolean"},"email_host":{"type":"boolean"},"sms_attendee":{"type":"boolean"}}},"description":"Per event, overriding your settings for this event type. `null`: only those."},"reminders":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SchedulingReminder"},"description":"What goes out around a booking, in place of your settings' list. `null` inherits it; an empty list means none."},"hosts":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string","description":"The host's id."},"role":{"type":"string","enum":["required","member"],"description":"`required` hosts must all be free; one `member` is chosen for a booking."},"weight":{"type":"number","description":"Share of a pool's bookings relative to other members."},"schedule":{"type":["string","null"],"description":"The id of the schedule used for this event type. `null`: the host's default schedule."}},"required":["host","role","weight","schedule"]},"description":"The hosts assigned by name."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","uid","description","title","kind","status","duration_minutes","duration_options","step_minutes","grid_time_zone","buffer_before_minutes","buffer_after_minutes","min_notice_minutes","booking_window","limits","capacity","requires_approval","reassignment_enabled","approval_ttl_minutes","hold_ttl_seconds","cancel_notice_minutes","reschedule_notice_minutes","max_guests","max_active_bookings_per_attendee","host_calendar_details","questions","locations","host_filter","notifications","reminders","hosts","metadata","created_at","updated_at"],"examples":[{"object":"scheduling.event_type","id":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","uid":null,"title":"Initial consultation","description":null,"kind":"one_on_one","status":"active","duration_minutes":30,"duration_options":[],"step_minutes":30,"grid_time_zone":null,"buffer_before_minutes":0,"buffer_after_minutes":10,"min_notice_minutes":120,"booking_window":null,"limits":[],"capacity":null,"requires_approval":false,"reassignment_enabled":true,"approval_ttl_minutes":1440,"hold_ttl_seconds":600,"cancel_notice_minutes":0,"reschedule_notice_minutes":0,"max_guests":0,"max_active_bookings_per_attendee":null,"host_calendar_details":"neutral","questions":[],"locations":[],"host_filter":null,"notifications":null,"reminders":null,"hosts":[{"host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","role":"member","weight":100,"schedule":null}],"metadata":{},"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"SchedulingBookingWindow":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["rolling"]},"days":{"type":"integer","minimum":1,"maximum":730,"description":"Days ahead of now that slots are offered."}},"required":["kind","days"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["range"]},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The first local date offered, `YYYY-MM-DD`.","examples":["2027-12-24"]},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last local date offered, `YYYY-MM-DD`.","examples":["2027-12-24"]}},"required":["kind","from","to"],"additionalProperties":false},{"type":"null"}],"description":"How far ahead a slot can be booked: `rolling` for a number of days from now, or `range` for fixed dates. On an event type, `null` means no window of its own."},"SchedulingLimit":{"type":"object","properties":{"period":{"type":"string","enum":["day","week"],"description":"In the host's time zone."},"max":{"type":"integer","minimum":1,"maximum":1000,"description":"The most bookings allowed in one period."},"scope":{"type":"string","enum":["event_type","host"],"default":"event_type","description":"Count this event type's bookings, or all of the host's."}},"required":["period","max"],"additionalProperties":false,"description":"A cap on bookings in a day or a week."},"SchedulingQuestion":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$","description":"The answer's key in `answers`. Unique within the event type."},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox","phone","email","number"],"description":"How it's asked and which answers are valid."},"label":{"type":"string","minLength":1,"maxLength":200,"description":"The question as attendees see it."},"required":{"type":"boolean","default":false,"description":"Whether a booking must answer it."},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":50,"default":[],"description":"The choices of a `select`, `radio` or `checkbox` question. `select` and `radio` need at least one."}},"required":["key","type","label"],"additionalProperties":false,"description":"Something attendees are asked when booking. Answers are encrypted, and come back only when you retrieve one booking."},"SchedulingReminder":{"type":"object","properties":{"key":{"type":"string","description":"What webhooks and the booking call this reminder."},"anchor":{"type":"string","enum":["start","end","confirmed","rescheduled","cancelled","declined","pending_approval","no_show"],"description":"The moment this is timed from."},"before_minutes":{"type":["number","null"],"description":"How long before the anchor. `null` when it's after."},"after_minutes":{"type":["number","null"],"description":"How long after the anchor. `null` when it's before."},"send":{"type":"array","items":{"type":"string","enum":["email_attendee","email_host","sms_attendee","sms_host","webhook"]},"description":"Who hears about it. `webhook` fires `scheduling.booking.reminder`."},"email_to":{"type":"array","items":{"type":"string"},"description":"Fixed addresses that are emailed as well."},"subject":{"type":["string","null"],"description":"Your own subject. `null`: the standard one."},"message":{"type":["string","null"],"description":"Your own words in the email. `null`: the standard ones."},"sms_message":{"type":["string","null"],"description":"Your own text. `null`: the standard one."},"button":{"type":["object","null"],"properties":{"label":{"type":"string","description":"What the button says."},"url":{"type":"string","description":"Where it goes."}},"required":["label","url"],"description":"One button in the email. `null`: none."},"include_invite":{"type":"boolean","description":"Whether the emails carry the invitation."},"send_if_late":{"type":"boolean","description":"Whether it goes right away if booked after its moment, instead of being skipped."},"skip_no_show":{"type":"boolean","description":"Whether it's dropped once the booking is marked a no-show."},"only_if":{"type":["object","null"],"properties":{"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"The booking's metadata must have all of these. `null`: any."},"location_types":{"type":["array","null"],"items":{"type":"string"},"description":"The booking's location must be one of these. `null`: any."}},"required":["metadata","location_types"],"description":"Only for bookings matching all of this. `null`: every booking."}},"required":["key","anchor","before_minutes","after_minutes","send","email_to","subject","message","sms_message","button","include_invite","send_if_late","skip_no_show","only_if"]},"CreateEventTypeRequest":{"type":"object","properties":{"uid":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for this event type, unique in the environment, accepted wherever its id is."},"kind":{"type":"string","enum":["one_on_one","pool","collective","group"],"default":"one_on_one","description":"Who a booking needs. `one_on_one`: one host. `pool`: any one of its hosts. `collective`: every `required` host, plus at most one `member`. `group`: one host, with attendees taking seats up to `capacity`. Fixed once created."},"description":{"type":["string","null"],"maxLength":2000,"description":"Plain text about the event type, shown on hosted booking pages and never in emails. Links, and anything shaped like a domain, must be on your organization's verified domains or their subdomains, and use `https`. `null` removes it."},"title":{"type":"string","minLength":1,"maxLength":120,"description":"Shown to attendees and in emails. Host calendars show it only with `host_calendar_details: full`."},"duration_minutes":{"type":"integer","minimum":5,"maximum":1440,"description":"How long a booking lasts by default, in minutes."},"duration_options":{"type":"array","items":{"type":"integer","minimum":5,"maximum":1440},"maxItems":10,"description":"Other lengths an attendee may choose, in minutes. Empty: only `duration_minutes`."},"step_minutes":{"type":"integer","minimum":5,"maximum":1440,"description":"How far apart slots start. Default: the duration."},"grid_time_zone":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"The zone slots align in. Default: each host's own.","examples":["America/New_York"]},"buffer_before_minutes":{"type":"integer","minimum":0,"maximum":480,"description":"Minutes kept free before each booking. Default: 0."},"buffer_after_minutes":{"type":"integer","minimum":0,"maximum":480,"description":"Minutes kept free after each booking. Default: 0."},"min_notice_minutes":{"type":"integer","minimum":0,"maximum":525600,"description":"Slots starting sooner than this many minutes from now aren't offered. Default: 0."},"booking_window":{"$ref":"#/components/schemas/SchedulingBookingWindow"},"limits":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingLimit"},"maxItems":4,"description":"Caps on bookings per day or week. Default: none."},"capacity":{"type":["integer","null"],"minimum":2,"maximum":10000,"description":"Attendees per session. Required for, and only allowed on, `group`."},"requires_approval":{"type":"boolean","description":"Bookings start as `pending_approval`, holding the time until approved or declined. Default: `false`."},"reassignment_enabled":{"type":"boolean","description":"Whether bookings of this event type can go to another host. Default: true."},"approval_ttl_minutes":{"type":"integer","minimum":5,"maximum":43200,"description":"How long a booking can wait for approval before it's declined, in minutes. Default: 1440."},"hold_ttl_seconds":{"type":"integer","minimum":60,"maximum":86400,"description":"How long a hold keeps its slot, in seconds. Default: 600."},"cancel_notice_minutes":{"type":"integer","minimum":0,"maximum":525600,"description":"Attendees can't cancel closer to the start than this. API keys can."},"reschedule_notice_minutes":{"type":"integer","minimum":0,"maximum":525600,"description":"Attendees can't reschedule closer to the start than this. API keys can. Default: 0."},"max_guests":{"type":"integer","minimum":0,"maximum":10,"description":"How many people an attendee can add to a booking. Default: 0. Guests are emailed about it. Not on `group`."},"max_active_bookings_per_attendee":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"How many upcoming bookings of this event type one person can have at a time, known by `uid` or email. Default: `null`, no limit. Past this, booking answers `attendee_limit_reached`. Guests don't count, and each occurrence of a series does."},"host_calendar_details":{"type":"string","enum":["neutral","full"],"description":"What hosts' calendars say about a booking. `neutral` (the default): a private event titled \"Appointment\". `full`: a private event with this title and the attendee's name, plus names, emails and phone numbers in its description, which go to the host's calendar provider. Never answers. Refused in HIPAA mode."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingQuestion"},"maxItems":25,"description":"What attendees are asked when booking. Keys must be unique."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingLocation"},"maxItems":10,"description":"Where bookings can meet. A browser only chooses among these. A `group` event type can't use `zoom`."},"host_filter":{"type":["object","null"],"additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Pool members also include active hosts matching all of these attributes."},"notifications":{"type":["object","null"],"additionalProperties":{"type":"object","properties":{"email_attendee":{"type":"boolean"},"email_host":{"type":"boolean"},"sms_attendee":{"type":"boolean"}},"additionalProperties":false},"description":"Per event, overriding your settings for this event type."},"reminders":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SchedulingReminderInput"},"maxItems":10,"description":"Replaces your settings' `reminders` for this event type. `null` inherits them; an empty list means none."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs."},"hosts":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingEventTypeHostInput"},"maxItems":500,"default":[],"description":"Who can be booked. `one_on_one` and `group` take one; `collective` needs at least one `required` host."}},"required":["title","duration_minutes"],"additionalProperties":false,"examples":[{"title":"Initial consultation","kind":"one_on_one","duration_minutes":30,"buffer_after_minutes":10,"min_notice_minutes":120,"hosts":[{"host":"doctor_482"}]}]},"SchedulingReminderInput":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$","description":"Names this reminder in webhooks and on the booking. Default: from its timing, like `start-1440`."},"anchor":{"type":"string","enum":["start","end","confirmed","rescheduled","cancelled","declined","pending_approval","no_show"],"description":"The moment this is timed from."},"before_minutes":{"type":["integer","null"],"minimum":0,"maximum":525600,"description":"How long before the anchor. Only for `start` and `end`."},"after_minutes":{"type":["integer","null"],"minimum":0,"maximum":86400,"description":"How long after the anchor, up to 60 days. Default for other anchors: 0."},"send":{"type":"array","items":{"type":"string","enum":["email_attendee","email_host","sms_attendee","sms_host","webhook"]},"maxItems":5,"description":"Who hears about it. `webhook` fires `scheduling.booking.reminder`."},"email_to":{"type":"array","items":{"type":"string","maxLength":320,"format":"email"},"maxItems":5,"description":"Fixed addresses to email as well: verified members of your organization, or addresses on your verified domains (live environments)."},"subject":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"Your own subject, with `{{variables}}`. Needs `email_from`."},"message":{"type":["string","null"],"minLength":1,"maxLength":2000,"description":"Your own words in place of the standard first line, with `{{variables}}` and no links. The booking's details stay below it. Needs `email_from`."},"sms_message":{"type":["string","null"],"minLength":1,"maxLength":320,"description":"Your own text, with `{{variables}}` other than names, and no links. `Reply STOP to opt out.` is always added."},"button":{"type":["object","null"],"properties":{"label":{"type":"string","minLength":1,"maxLength":40},"url":{"type":"string","minLength":1,"maxLength":500,"description":"https, on one of your verified domains (live environments). May use `{{booking_id}}` in its path or query.","examples":["https://example.com/feedback?booking={{booking_id}}"]}},"required":["label","url"],"additionalProperties":false,"description":"One button in the email. Needs `email_from`."},"include_invite":{"type":"boolean","description":"Attach the calendar invitation to the emails."},"send_if_late":{"type":"boolean","description":"If it was booked after this reminder's moment, send it right away instead of skipping it, as long as the meeting is still ahead. Only for `before_minutes` on `start`."},"skip_no_show":{"type":"boolean","description":"Don't send it once the booking is marked a no-show. Default: true on `end`."},"only_if":{"type":["object","null"],"properties":{"metadata":{"type":["object","null"],"additionalProperties":{"type":"string","maxLength":500},"description":"The booking's metadata must have all of these."},"location_types":{"type":["array","null"],"items":{"type":"string","enum":["link","phone","in_person","google_meet","microsoft_teams","zoom"]},"minItems":1,"maxItems":6,"description":"The booking's location must be one of these."}},"additionalProperties":false,"description":"Only for bookings matching all of this, checked when it's due."}},"required":["anchor"],"additionalProperties":false},"SchedulingEventTypeHostInput":{"type":"object","properties":{"host":{"type":"string","description":"The host's id or uid."},"role":{"type":"string","enum":["required","member"],"default":"member","description":"`required` hosts must all be free; one `member` is chosen for a booking."},"weight":{"type":"integer","minimum":1,"maximum":10000,"default":100,"description":"Share of a pool's bookings relative to other members."},"schedule":{"type":["string","null"],"default":null,"description":"A schedule of this host's. Default: their default schedule."}},"required":["host"],"additionalProperties":false},"SchedulingEventTypeList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingEventType"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.event_type","id":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","uid":null,"title":"Initial consultation","description":null,"kind":"one_on_one","status":"active","duration_minutes":30,"duration_options":[],"step_minutes":30,"grid_time_zone":null,"buffer_before_minutes":0,"buffer_after_minutes":10,"min_notice_minutes":120,"booking_window":null,"limits":[],"capacity":null,"requires_approval":false,"reassignment_enabled":true,"approval_ttl_minutes":1440,"hold_ttl_seconds":600,"cancel_notice_minutes":0,"reschedule_notice_minutes":0,"max_guests":0,"max_active_bookings_per_attendee":null,"host_calendar_details":"neutral","questions":[],"locations":[],"host_filter":null,"notifications":null,"reminders":null,"hosts":[{"host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","role":"member","weight":100,"schedule":null}],"metadata":{},"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"UpdateEventTypeRequest":{"type":"object","properties":{"uid":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Your own id for this event type. `null` removes it."},"description":{"type":["string","null"],"maxLength":2000,"description":"Plain text about the event type, shown on hosted booking pages and never in emails. Links, and anything shaped like a domain, must be on your organization's verified domains or their subdomains, and use `https`. `null` removes it."},"title":{"type":"string","minLength":1,"maxLength":120,"description":"Shown to attendees and in emails. Host calendars show it only with `host_calendar_details: full`."},"duration_minutes":{"type":"integer","minimum":5,"maximum":1440,"description":"How long a booking lasts by default, in minutes."},"duration_options":{"type":"array","items":{"type":"integer","minimum":5,"maximum":1440},"maxItems":10,"description":"Other lengths an attendee may choose, in minutes. Empty: only `duration_minutes`."},"step_minutes":{"type":"integer","minimum":5,"maximum":1440,"description":"How far apart slots start. Default: the duration."},"grid_time_zone":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"The zone slots align in. Default: each host's own.","examples":["America/New_York"]},"buffer_before_minutes":{"type":"integer","minimum":0,"maximum":480,"description":"Minutes kept free before each booking. Default: 0."},"buffer_after_minutes":{"type":"integer","minimum":0,"maximum":480,"description":"Minutes kept free after each booking. Default: 0."},"min_notice_minutes":{"type":"integer","minimum":0,"maximum":525600,"description":"Slots starting sooner than this many minutes from now aren't offered. Default: 0."},"booking_window":{"$ref":"#/components/schemas/SchedulingBookingWindow"},"limits":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingLimit"},"maxItems":4,"description":"Caps on bookings per day or week. Default: none."},"capacity":{"type":["integer","null"],"minimum":2,"maximum":10000,"description":"Attendees per session. Required for, and only allowed on, `group`."},"requires_approval":{"type":"boolean","description":"Bookings start as `pending_approval`, holding the time until approved or declined. Default: `false`."},"reassignment_enabled":{"type":"boolean","description":"Whether bookings of this event type can go to another host. Default: true."},"approval_ttl_minutes":{"type":"integer","minimum":5,"maximum":43200,"description":"How long a booking can wait for approval before it's declined, in minutes. Default: 1440."},"hold_ttl_seconds":{"type":"integer","minimum":60,"maximum":86400,"description":"How long a hold keeps its slot, in seconds. Default: 600."},"cancel_notice_minutes":{"type":"integer","minimum":0,"maximum":525600,"description":"Attendees can't cancel closer to the start than this. API keys can."},"reschedule_notice_minutes":{"type":"integer","minimum":0,"maximum":525600,"description":"Attendees can't reschedule closer to the start than this. API keys can. Default: 0."},"max_guests":{"type":"integer","minimum":0,"maximum":10,"description":"How many people an attendee can add to a booking. Default: 0. Guests are emailed about it. Not on `group`."},"max_active_bookings_per_attendee":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"How many upcoming bookings of this event type one person can have at a time, known by `uid` or email. Default: `null`, no limit. Past this, booking answers `attendee_limit_reached`. Guests don't count, and each occurrence of a series does."},"host_calendar_details":{"type":"string","enum":["neutral","full"],"description":"What hosts' calendars say about a booking. `neutral` (the default): a private event titled \"Appointment\". `full`: a private event with this title and the attendee's name, plus names, emails and phone numbers in its description, which go to the host's calendar provider. Never answers. Refused in HIPAA mode."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingQuestion"},"maxItems":25,"description":"What attendees are asked when booking. Keys must be unique."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingLocation"},"maxItems":10,"description":"Where bookings can meet. A browser only chooses among these. A `group` event type can't use `zoom`."},"host_filter":{"type":["object","null"],"additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Pool members also include active hosts matching all of these attributes."},"notifications":{"type":["object","null"],"additionalProperties":{"type":"object","properties":{"email_attendee":{"type":"boolean"},"email_host":{"type":"boolean"},"sms_attendee":{"type":"boolean"}},"additionalProperties":false},"description":"Per event, overriding your settings for this event type."},"reminders":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SchedulingReminderInput"},"maxItems":10,"description":"Replaces your settings' `reminders` for this event type. `null` inherits them; an empty list means none."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs."},"status":{"type":"string","enum":["active","archived"],"description":"`archived` stops new bookings, and keeps existing ones."},"hosts":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingEventTypeHostInput"},"maxItems":500,"description":"Replaces the assigned hosts. Removed hosts keep their existing bookings."}},"additionalProperties":false,"examples":[{"min_notice_minutes":240}]},"SchedulingSlotList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingSlot"}},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z","hosts":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"],"seats_left":null}],"has_more":false}]},"SchedulingSlot":{"type":"object","properties":{"start":{"type":"string","description":"When the slot starts."},"end":{"type":"string","description":"When the slot ends."},"hosts":{"type":"array","items":{"type":"string"},"description":"Who could take it."},"seats_left":{"type":["number","null"],"description":"Free seats at this start, for a `group` event type. `null` for the others."}},"required":["start","end","hosts","seats_left"]},"SchedulingSlotExplanation":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.slot_explanation"]},"start":{"type":"string","description":"The start asked about."},"end":{"type":"string","description":"When it would end."},"available":{"type":"boolean","description":"Whether it can be booked right now."},"reason":{"type":["string","null"],"description":"Why it can't: `not_on_grid`, `too_soon`, `outside_booking_window`, `out_of_office`, `outside_coverage`, `calendar_unverified`, `outside_availability`, `host_busy`, `already_claimed`, `limit_reached` or `session_full`, or `event_type_inactive` or `no_hosts`. `null` when it can. With several hosts refused, the first one's reason: see `hosts`."},"hosts":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string","description":"The host's id."},"role":{"type":"string","enum":["required","member"],"description":"`required` hosts must all be free. Only one `member` needs to be."},"available":{"type":"boolean","description":"Whether this host could take it."},"reason":{"type":["string","null"],"description":"Why not: `not_on_grid`, `too_soon`, `outside_booking_window`, `out_of_office`, `outside_coverage`, `calendar_unverified`, `outside_availability`, `host_busy`, `already_claimed`, `limit_reached` or `session_full`. `null` when they could."},"calendar_reason":{"type":["string","null"],"description":"With `calendar_unverified`: `calendar_needs_reauth`, `calendar_stale` or `calendar_not_covered`."}},"required":["host","role","available","reason","calendar_reason"]},"description":"Everyone who could take this event type, narrowed by the query."}},"required":["object","start","end","available","reason","hosts"],"examples":[{"object":"scheduling.slot_explanation","start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z","available":false,"reason":"host_busy","hosts":[{"host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","role":"member","available":false,"reason":"host_busy","calendar_reason":null}]}]},"SchedulingAvailabilitySearchResult":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string","description":"The host's id."},"uid":{"type":["string","null"],"description":"The host's own uid. `null` when none is set."},"slots":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"When the slot starts."},"end":{"type":"string","description":"When the slot ends."}},"required":["start","end"]},"description":"The host's soonest slots."}},"required":["host","uid","slots"]},"description":"Each host with availability, soonest first."},"has_more":{"type":"boolean","description":"Whether more hosts matched than `limit` returned."}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","uid":"doctor_482","slots":[{"start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z"}]}],"has_more":false}]},"AvailabilitySearchRequest":{"type":"object","properties":{"event_type":{"type":"string","description":"The event type's id or uid."},"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"end":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Only hosts matching all of these."},"hosts":{"type":"array","items":{"type":"string"},"maxItems":500,"description":"Only these hosts (ids or uids). Default: everyone the event type could offer."},"slots_per_host":{"type":"integer","minimum":1,"maximum":50,"default":3,"description":"How many of each host's soonest slots to return."},"limit":{"type":"integer","minimum":1,"maximum":500,"default":50,"description":"Hosts to return, soonest availability first."}},"required":["event_type","start","end"],"additionalProperties":false,"examples":[{"event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","start":"2027-01-04T00:00:00.000Z","end":"2027-01-18T00:00:00.000Z","attributes":{"licensed_in":"CA"}}]},"CreateBookingRequest":{"type":"object","properties":{"event_type":{"type":"string","description":"The event type's id or uid."},"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"host":{"type":"string","description":"A specific host (id or uid). Default: chosen fairly from those free."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Only choose among pool hosts matching all of these."},"duration_minutes":{"type":"integer","minimum":5,"maximum":1440,"description":"One of the event type's `duration_options`."},"attendee":{"$ref":"#/components/schemas/SchedulingAttendeeInput"},"guests":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingGuestInput"},"maxItems":10,"description":"Up to the event type's `max_guests`."},"answers":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"array","items":{"type":"string","maxLength":500},"maxItems":50}]},"description":"Answers to the event type's questions. Stored encrypted, and returned only by retrieving the booking."},"location":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["link"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting link. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["phone"]},"number":{"type":["string","null"],"maxLength":32,"default":null,"description":"The phone number to call. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["in_person"]},"address":{"type":["string","null"],"maxLength":500,"default":null,"description":"The address to meet at. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["google_meet"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["microsoft_teams"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["zoom"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting's link, once it's created on the host's Zoom account."}},"required":["type"],"additionalProperties":false}],"description":"One of the event type's `locations`, with your link filled in if it has none."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs. Don't put sensitive data here."}},"required":["event_type","start","attendee"],"additionalProperties":false,"examples":[{"event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","start":"2027-01-04T15:00:00.000Z","attendee":{"uid":"patient_77","name":"Sam Lee","email":"sam@example.com","time_zone":"UTC"}}]},"SchedulingAttendeeInput":{"type":"object","properties":{"uid":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for this person, used to erase their data later."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Needed for coss.com to notify them. Can't contain a link."},"email":{"type":"string","maxLength":320,"format":"email","description":"Where coss.com emails them, if it does."},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"An E.164 number, for SMS reminders."},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"Their IANA time zone. A series keeps their local time across clock changes.","examples":["America/New_York"]},"locale":{"type":"string","minLength":2,"maxLength":35,"description":"Their locale, such as `en-US`. Emails and texts about the booking are written in it when coss.com has it, otherwise in English, and guests get the same."}},"required":["time_zone"],"additionalProperties":false,"description":"Name and email are only needed if coss.com notifies this attendee."},"SchedulingGuestInput":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","description":"Where they're emailed about the booking."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Their name, if you have it."}},"required":["email"],"additionalProperties":false,"description":"Someone else coming along. They're emailed about the booking, with no manage link."},"SchedulingBookingList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingBooking"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.booking","id":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"confirmed","title":"Initial consultation","start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z","hosts":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"],"attendees":[{"id":"attn_01kd2m9a0b1c2d3e4f5g6h7j8m","role":"attendee","uid":"patient_77","name":"Sam Lee","email":"sam@example.com","phone":null,"time_zone":"UTC","locale":null}],"location":null,"hold_expires_at":null,"approval_expires_at":null,"series":null,"series_index":null,"group_session":null,"calendar_unverified":false,"external_conflict_at":null,"no_show_at":null,"cancelled_at":null,"cancelled_by":null,"metadata":{},"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"RescheduleBookingRequest":{"type":"object","properties":{"start":{"type":"string","description":"The new start. The old time stays booked unless this one's free.","examples":["2027-01-04T15:00:00.000Z"]},"host":{"type":"string","description":"Move a pool booking to this host. Default: its current hosts."}},"required":["start"],"additionalProperties":false,"examples":[{"start":"2027-01-05T15:00:00.000Z"}]},"CancelSchedulingBookingRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Why it's being cancelled. Only retrieving this booking returns it: it's never in webhooks, logs or emails."}},"additionalProperties":false,"examples":[{"reason":"Feeling better"}]},"SchedulingBookingEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingBookingEvent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.booking_event","id":"bevt_01kd2m9a0b1c2d3e4f5g6h7j8m","sequence":1,"type":"scheduling.booking.confirmed","actor":{"kind":"api_key","id":"key_01kd2m9a0b1c2d3e4f5g6h7j8m"},"details":{},"occurred_at":"2027-01-02T09:00:00.000Z"}],"has_more":false}]},"SchedulingBookingEvent":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.booking_event"]},"id":{"type":"string"},"sequence":{"type":"number","description":"This booking's events count up from 1."},"type":{"type":"string","description":"What happened, such as `scheduling.booking.confirmed`, `scheduling.booking.rescheduled` or `scheduling.booking.cancelled`."},"actor":{"type":"object","properties":{"kind":{"type":"string","enum":["api_key","user","host_session","booker_session","manage_session","manager_session","system"]},"id":{"type":["string","null"],"description":"The API key, user or session's id. `null` for `system`."}},"required":["kind","id"],"description":"Who did it."},"details":{"type":"object","additionalProperties":{},"description":"More about it, such as `previous_start` on a reschedule. Never personal data."},"occurred_at":{"type":"string","description":"When it happened."}},"required":["object","id","sequence","type","actor","details","occurred_at"]},"SchedulingBookingNotificationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingBookingNotification"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.booking_notification","id":"sntf_01kd2m9a0b1c2d3e4f5g6h7j8m","kind":"reminder","reminder_key":"start-1440","channel":"email","recipient":"attendee","due_at":"2027-01-03T15:00:00.000Z","finished_at":null,"outcome":null}],"has_more":false}]},"SchedulingBookingNotification":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.booking_notification"]},"id":{"type":"string"},"kind":{"type":"string","description":"`reminder` for an entry of `reminders`; otherwise a standard notification, or `started`/`ended`."},"reminder_key":{"type":["string","null"]},"channel":{"type":"string","enum":["email","sms","webhook"]},"recipient":{"type":"string","enum":["attendee","host","endpoint","address"]},"due_at":{"type":"string"},"finished_at":{"type":["string","null"]},"outcome":{"type":["string","null"],"description":"`null` while it's waiting. `sent`, or why not: `too_late`, `filtered`, `no_show`, `no_address`, `no_sender`, `stale`, `superseded`, `failed`."}},"required":["object","id","kind","reminder_key","channel","recipient","due_at","finished_at","outcome"],"examples":[{"object":"scheduling.booking_notification","id":"sntf_01kd2m9a0b1c2d3e4f5g6h7j8m","kind":"reminder","reminder_key":"start-1440","channel":"email","recipient":"attendee","due_at":"2027-01-03T15:00:00.000Z","finished_at":null,"outcome":null}]},"UpdateBookingLocationRequest":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/SchedulingLocation"}},"required":["location"],"additionalProperties":false,"examples":[{"location":{"type":"link","url":"https://meet.example.com/abc"}}]},"CreateHoldRequest":{"type":"object","properties":{"event_type":{"type":"string","description":"The event type's id or uid."},"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"host":{"type":"string","description":"A specific host (id or uid). Default: chosen fairly from those free."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Only choose among pool hosts matching all of these."},"duration_minutes":{"type":"integer","minimum":5,"maximum":1440,"description":"One of the event type's `duration_options`."},"attendee":{"$ref":"#/components/schemas/SchedulingAttendeeInput"},"guests":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingGuestInput"},"maxItems":10,"description":"Up to the event type's `max_guests`."},"answers":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"array","items":{"type":"string","maxLength":500},"maxItems":50}]},"description":"Answers to the event type's questions. Stored encrypted, and returned only by retrieving the booking."},"location":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["link"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting link. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["phone"]},"number":{"type":["string","null"],"maxLength":32,"default":null,"description":"The phone number to call. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["in_person"]},"address":{"type":["string","null"],"maxLength":500,"default":null,"description":"The address to meet at. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["google_meet"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["microsoft_teams"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["zoom"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting's link, once it's created on the host's Zoom account."}},"required":["type"],"additionalProperties":false}],"description":"One of the event type's `locations`, with your link filled in if it has none."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs. Don't put sensitive data here."}},"required":["event_type","start","attendee"],"additionalProperties":false,"examples":[{"event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","start":"2027-01-04T15:00:00.000Z","attendee":{"uid":"patient_77","time_zone":"UTC"}}]},"ConfirmHoldRequest":{"type":"object","properties":{"if_still_free":{"type":"boolean","default":false,"description":"After the hold expired, book anyway if nobody else took the slot. Default: refuse with `hold_expired`."}},"additionalProperties":false,"examples":[{"if_still_free":true}]},"SchedulingSeries":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.series"]},"id":{"type":"string"},"bookings":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingBooking"},"description":"The occurrences booked, each an ordinary booking."},"conflicts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"The occurrence's place in the series, from 0."},"start":{"type":"string","description":"When it would have started."}},"required":["index","start"]},"description":"With `on_conflict: skip`, the occurrences that weren't free and weren't booked."}},"required":["object","id","bookings","conflicts"],"examples":[{"object":"scheduling.series","id":"series_01kd2m9a0b1c2d3e4f5g6h7j8m","bookings":[{"object":"scheduling.booking","id":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"confirmed","title":"Initial consultation","start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z","hosts":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"],"attendees":[{"id":"attn_01kd2m9a0b1c2d3e4f5g6h7j8m","role":"attendee","uid":"patient_77","name":"Sam Lee","email":"sam@example.com","phone":null,"time_zone":"UTC","locale":null}],"location":null,"hold_expires_at":null,"approval_expires_at":null,"series":null,"series_index":null,"group_session":null,"calendar_unverified":false,"external_conflict_at":null,"no_show_at":null,"cancelled_at":null,"cancelled_by":null,"metadata":{},"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"conflicts":[]}]},"CreateSeriesRequest":{"type":"object","properties":{"event_type":{"type":"string","description":"The event type's id or uid."},"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"host":{"type":"string","description":"A specific host (id or uid). Default: chosen fairly from those free."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Only choose among pool hosts matching all of these."},"duration_minutes":{"type":"integer","minimum":5,"maximum":1440,"description":"One of the event type's `duration_options`."},"attendee":{"$ref":"#/components/schemas/SchedulingAttendeeInput"},"guests":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingGuestInput"},"maxItems":10,"description":"Up to the event type's `max_guests`."},"answers":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"array","items":{"type":"string","maxLength":500},"maxItems":50}]},"description":"Answers to the event type's questions. Stored encrypted, and returned only by retrieving the booking."},"location":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["link"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting link. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["phone"]},"number":{"type":["string","null"],"maxLength":32,"default":null,"description":"The phone number to call. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["in_person"]},"address":{"type":["string","null"],"maxLength":500,"default":null,"description":"The address to meet at. `null` on an event type means the booking supplies its own."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["google_meet"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["microsoft_teams"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["zoom"]},"url":{"type":["string","null"],"maxLength":2000,"format":"uri","default":null,"description":"The meeting's link, once it's created on the host's Zoom account."}},"required":["type"],"additionalProperties":false}],"description":"One of the event type's `locations`, with your link filled in if it has none."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs. Don't put sensitive data here."},"recurrence":{"type":"object","properties":{"frequency":{"type":"string","enum":["weekly","monthly"],"description":"Repeat weekly or monthly."},"interval":{"type":"integer","minimum":1,"maximum":12,"default":1,"description":"Every this many weeks or months. Default: 1."},"count":{"type":"integer","minimum":2,"maximum":52,"description":"Occurrences in total, the first included."}},"required":["frequency","count"],"additionalProperties":false,"description":"How often the booking repeats, at the attendee's local time."},"on_conflict":{"type":"string","enum":["reject","skip"],"default":"reject","description":"If an occurrence isn't free: book nothing, or book the rest and report it."}},"required":["event_type","start","attendee","recurrence"],"additionalProperties":false,"examples":[{"event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","start":"2027-01-04T15:00:00.000Z","attendee":{"uid":"patient_77","time_zone":"America/New_York"},"recurrence":{"frequency":"weekly","interval":1,"count":12}}]},"SchedulingSeriesPreview":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"When this occurrence starts."},"available":{"type":"boolean","description":"Whether it's free."},"reason":{"type":["string","null"],"description":"Why it isn't free, such as `host_busy`, `already_claimed`, `outside_availability` or `no_hosts`. `null` when it is."},"hosts":{"type":"array","items":{"type":"string"},"description":"The ids of the hosts who could take it."}},"required":["start","available","reason","hosts"]},"description":"Each occurrence the request would book. Nothing is booked."},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"start":"2027-01-04T15:00:00.000Z","available":true,"reason":null,"hosts":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]}],"has_more":false}]},"SchedulingCancelledSeries":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingBooking"}},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.booking","id":"book_01kd2m9a0b1c2d3e4f5g6h7j8m","event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","status":"confirmed","title":"Initial consultation","start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T15:30:00.000Z","hosts":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"],"attendees":[{"id":"attn_01kd2m9a0b1c2d3e4f5g6h7j8m","role":"attendee","uid":"patient_77","name":"Sam Lee","email":"sam@example.com","phone":null,"time_zone":"UTC","locale":null}],"location":null,"hold_expires_at":null,"approval_expires_at":null,"series":null,"series_index":null,"group_session":null,"calendar_unverified":false,"external_conflict_at":null,"no_show_at":null,"cancelled_at":null,"cancelled_by":null,"metadata":{},"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"CancelSeriesRequest":{"type":"object","properties":{"from_index":{"type":"integer","minimum":0,"default":0,"description":"Cancel this occurrence and those after it. Default: all of them."}},"additionalProperties":false,"examples":[{"from_index":4}]},"SchedulingAttendeeErasure":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.attendee_erasure"]},"uid":{"type":"string","description":"The attendee's uid."},"erased":{"type":"number","description":"How many attendee records were erased, one per booking."}},"required":["object","uid","erased"],"examples":[{"object":"scheduling.attendee_erasure","uid":"patient_77","erased":3}]},"SchedulingAttendeeErasureByEmail":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.attendee_erasure"]},"erased":{"type":"number","description":"How many attendee and guest records were erased."}},"required":["object","erased"],"examples":[{"object":"scheduling.attendee_erasure","erased":3}]},"EraseSchedulingAttendeeByEmailRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","description":"The address to forget, an attendee's or a guest's."}},"required":["email"],"additionalProperties":false,"examples":[{"email":"sam@example.com"}]},"SchedulingCalendarAuthorization":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.calendar_authorization"]},"url":{"type":"string","description":"Open it in a new window: providers refuse to be framed."}},"required":["object","url"],"examples":[{"object":"scheduling.calendar_authorization","url":"https://accounts.google.com/o/oauth2/v2/auth?client_id=abc"}]},"AuthorizeCalendarRequest":{"type":"object","properties":{"provider":{"type":"string","enum":["google","microsoft","zoom"],"description":"Whose consent page to open. CalDAV connects with a password instead."},"return_url":{"type":"string","maxLength":2000,"format":"uri","description":"Where to send the browser afterwards, on one of the environment's allowed origins. `coss_calendar` says what happened: `connected`, `denied` or `invalid`."}},"required":["provider"],"additionalProperties":false,"examples":[{"provider":"google"}]},"SchedulingCalendarConnection":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.calendar_connection"]},"id":{"type":"string"},"host":{"type":"string","description":"The id of the host it belongs to."},"provider":{"type":"string","enum":["google","microsoft","caldav","simulated","zoom"],"description":"Where the calendar lives. `simulated` exists only in sandbox environments; `zoom` is only used for meetings, never read for busy times."},"account":{"type":"string","description":"The provider's account, such as the Google address."},"status":{"type":"string","enum":["active","needs_reauth"],"description":"`needs_reauth`: access was lost, and this host isn't offered until it's back."},"oauth_app":{"type":["string","null"],"description":"Your own OAuth app this connection's access came through. `null`: coss.com's, or no consent was involved."},"delegation":{"type":["string","null"],"description":"The calendar delegation that manages this connection. It can't be disconnected or reconnected by itself."},"calendars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"external_id":{"type":"string","description":"The calendar's id at the provider."},"read_busy":{"type":"boolean","description":"Whether its busy times block slots."},"write_target":{"type":"boolean","description":"Whether bookings are written to it."},"verified_at":{"type":["string","null"],"description":"When it was last read successfully. `null`: not read yet."}},"required":["id","external_id","read_busy","write_target","verified_at"]},"description":"The account's calendars."},"created_at":{"type":"string"}},"required":["object","id","host","provider","account","status","oauth_app","delegation","calendars","created_at"],"examples":[{"object":"scheduling.calendar_connection","id":"calconn_01kd2m9a0b1c2d3e4f5g6h7j8m","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","account":"ana@example.com","status":"active","delegation":null,"oauth_app":null,"calendars":[{"id":"cal_01kd2m9a0b1c2d3e4f5g6h7j8m","external_id":"ana@example.com","read_busy":true,"write_target":true,"verified_at":"2027-01-01T10:00:00.000Z"}],"created_at":"2027-01-01T10:00:00.000Z"}]},"CreateCalendarConnectionRequest":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["caldav"]},"url":{"type":"string","maxLength":2000,"format":"uri","description":"The server's https URL."},"username":{"type":"string","minLength":1,"maxLength":320,"description":"The account's username on that server."},"password":{"type":"string","minLength":1,"maxLength":500,"description":"An app-specific password. Encrypted, and never returned."}},"required":["provider","url","username","password"],"additionalProperties":false},{"type":"object","properties":{"provider":{"type":"string","enum":["simulated"]}},"required":["provider"],"additionalProperties":false}],"description":"`caldav` connects a server with an app-specific password; `simulated` is a sandbox calendar for tests.","examples":[{"provider":"caldav","url":"https://caldav.icloud.com","username":"ana@example.com","password":"abcd-efgh-ijkl-mnop"}]},"SchedulingCalendarConnectionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingCalendarConnection"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.calendar_connection","id":"calconn_01kd2m9a0b1c2d3e4f5g6h7j8m","host":"host_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","account":"ana@example.com","status":"active","delegation":null,"oauth_app":null,"calendars":[{"id":"cal_01kd2m9a0b1c2d3e4f5g6h7j8m","external_id":"ana@example.com","read_busy":true,"write_target":true,"verified_at":"2027-01-01T10:00:00.000Z"}],"created_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"DeletedSchedulingCalendarConnection":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.calendar_connection"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"scheduling.calendar_connection","id":"calconn_01kd2m9a0b1c2d3e4f5g6h7j8m","deleted":true}]},"UpdateCalendarRequest":{"type":"object","properties":{"read_busy":{"type":"boolean","description":"Whether this calendar's busy times block slots."},"write_target":{"type":"boolean","description":"Bookings are written to one calendar; setting this moves it here."}},"additionalProperties":false,"examples":[{"read_busy":true}]},"SchedulingCalendarDelegation":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.calendar_delegation"]},"id":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft"]},"domain":{"type":"string"},"status":{"type":"string","enum":["pending","active","failing","deleting"],"description":"`pending`: not verified yet. `failing`: the provider refused access, and its hosts aren't offered until it's back. `deleting`: its connections are being removed."},"match_host_email":{"type":"boolean"},"client_id":{"type":"string","description":"Google: the numeric client ID your Workspace admin authorizes."},"tenant_id":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"},"description":"What to authorize: OAuth scopes in Google's Admin console, the application permission in Entra."},"verified_account":{"type":["string","null"]},"last_error_code":{"type":["string","null"]},"failing_since":{"type":["string","null"]},"secret_expires_at":{"type":["string","null"]},"hosts_connected":{"type":"integer"},"hosts_failed":{"type":"integer","description":"Hosts whose mailbox can't be reached, or who are out while this is `failing`."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","provider","domain","status","match_host_email","client_id","tenant_id","scopes","verified_account","last_error_code","failing_since","secret_expires_at","hosts_connected","hosts_failed","created_at","updated_at"],"examples":[{"object":"scheduling.calendar_delegation","id":"caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","domain":"example.com","status":"active","match_host_email":true,"client_id":"117063284751902345678","tenant_id":null,"scopes":["https://www.googleapis.com/auth/calendar.events.freebusy"],"verified_account":"ana@example.com","last_error_code":null,"failing_since":null,"secret_expires_at":null,"hosts_connected":240,"hosts_failed":1,"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"CreateCalendarDelegationRequest":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["google"]},"domain":{"type":"string","maxLength":253,"pattern":"^[a-zA-Z0-9-]+(\\.[a-zA-Z0-9-]+)+$","description":"The Workspace or Microsoft 365 domain. Only addresses on exactly this domain connect, not its subdomains."},"match_host_email":{"type":"boolean","description":"Whether a host's `email` picks their mailbox when `calendar_account` isn't set. Turn it off if end users can type their own email into your app: otherwise one could name a colleague's address and reach that calendar."},"service_account_key":{"type":"string","maxLength":10000,"description":"The whole JSON key of a service account in your Google Cloud project. Never returned."}},"required":["provider","domain","service_account_key"],"additionalProperties":false},{"type":"object","properties":{"provider":{"type":"string","enum":["microsoft"]},"domain":{"type":"string","maxLength":253,"pattern":"^[a-zA-Z0-9-]+(\\.[a-zA-Z0-9-]+)+$","description":"The Workspace or Microsoft 365 domain. Only addresses on exactly this domain connect, not its subdomains."},"match_host_email":{"type":"boolean","description":"Whether a host's `email` picks their mailbox when `calendar_account` isn't set. Turn it off if end users can type their own email into your app: otherwise one could name a colleague's address and reach that calendar."},"tenant_id":{"type":"string","maxLength":100,"description":"The Directory (tenant) ID."},"client_id":{"type":"string","maxLength":100,"description":"The Application (client) ID."},"client_secret":{"type":"string","maxLength":1000,"description":"A client secret of that app. Never returned."},"secret_expires_at":{"type":"string","format":"date-time","description":"When the Entra client secret expires. Owners and admins are warned 14 days before."}},"required":["provider","domain","tenant_id","client_id","client_secret"],"additionalProperties":false}],"examples":[{"provider":"microsoft","domain":"example.com","tenant_id":"7d3f1c52-8e0b-4d6e-9a27-5c4b1e7d2f60","client_id":"3f1c7a52-8e0b-4d6e-9a27-5c4b1e7d2f60","client_secret":"abc~defghijklmnopqrstuvwxyz"}]},"SchedulingCalendarDelegationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingCalendarDelegation"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.calendar_delegation","id":"caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","domain":"example.com","status":"active","match_host_email":true,"client_id":"117063284751902345678","tenant_id":null,"scopes":["https://www.googleapis.com/auth/calendar.events.freebusy"],"verified_account":"ana@example.com","last_error_code":null,"failing_since":null,"secret_expires_at":null,"hosts_connected":240,"hosts_failed":1,"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"UpdateCalendarDelegationRequest":{"type":"object","properties":{"match_host_email":{"type":"boolean","description":"Whether a host's `email` picks their mailbox when `calendar_account` isn't set. Turn it off if end users can type their own email into your app: otherwise one could name a colleague's address and reach that calendar."},"service_account_key":{"type":"string","maxLength":10000,"description":"A new key. It's tried on the verified mailbox before it replaces the old one."},"client_secret":{"type":"string","maxLength":1000,"description":"A new client secret. It's tried on the verified mailbox before it replaces the old one."},"secret_expires_at":{"type":["string","null"],"format":"date-time","description":"When the Entra client secret expires. Owners and admins are warned 14 days before."}},"additionalProperties":false,"examples":[{"match_host_email":false}]},"VerifyCalendarDelegationRequest":{"type":"object","properties":{"account":{"type":"string","maxLength":320,"format":"email","description":"A real mailbox on the domain to try. In Microsoft 365, a user principal name."}},"required":["account"],"additionalProperties":false,"examples":[{"account":"ana@example.com"}]},"DeletedSchedulingCalendarDelegation":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.calendar_delegation"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"scheduling.calendar_delegation","id":"caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m","deleted":true}]},"SchedulingOauthApp":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.oauth_app"]},"id":{"type":"string"},"provider":{"type":"string","enum":["google","microsoft","zoom"]},"client_id":{"type":"string"},"tenant_id":{"type":["string","null"]},"redirect_uri":{"type":["string","null"]},"coss_callback_url":{"type":"string","description":"Register this with the provider if `redirect_uri` isn't set. If it is, that page forwards `code` and `state` here."},"completion_url":{"type":["string","null"]},"zoom_event_url":{"type":["string","null"],"description":"Zoom only: the Event notification endpoint URL for your app's deauthorization events."},"scopes":{"type":"array","items":{"type":"string"},"description":"What to enable on your app at the provider."},"status":{"type":"string","enum":["active","failing"],"description":"`failing`: the provider refused the app's credentials. New consents are refused, and calendars connected through it can't be read until they work again."},"last_error_code":{"type":["string","null"]},"last_error_at":{"type":["string","null"]},"secret_expires_at":{"type":["string","null"]},"verified_at":{"type":["string","null"],"description":"When a consent first completed through this app, which proves its secret."},"connections":{"type":"integer","description":"Calendar connections using this app. It can't be deleted while there are any."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","provider","client_id","tenant_id","redirect_uri","coss_callback_url","completion_url","zoom_event_url","scopes","status","last_error_code","last_error_at","secret_expires_at","verified_at","connections","created_at","updated_at"],"examples":[{"object":"scheduling.oauth_app","id":"calapp_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","client_id":"1234567890-abc.apps.googleusercontent.com","tenant_id":null,"redirect_uri":"https://example.com/oauth/google","coss_callback_url":"https://api.coss.com/scheduling/oauth/google/callback","completion_url":"https://example.com/calendar-connected","zoom_event_url":null,"scopes":["https://www.googleapis.com/auth/calendar.events.freebusy"],"status":"active","last_error_code":null,"last_error_at":null,"secret_expires_at":null,"verified_at":"2027-01-01T10:00:00.000Z","connections":12,"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}]},"CreateOauthAppRequest":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["google"]},"client_id":{"type":"string","minLength":1,"maxLength":500,"pattern":"^\\S+$","description":"The app's client ID at the provider."},"client_secret":{"type":"string","minLength":1,"maxLength":1000,"description":"The app's client secret. Never returned."},"redirect_uri":{"type":"string","maxLength":2000,"description":"A page on your own domain, registered with the provider, that forwards `code` and `state` to `coss_callback_url`. Google requires this for an external app, since it has to verify the redirect's domain as yours. Leave it out to use `coss_callback_url` directly."},"completion_url":{"type":"string","maxLength":2000,"description":"Where the browser lands after a consent that didn't name a `return_url`, with `coss_calendar` set to `connected`, `denied` or `invalid`. Leave it out for a plain page saying what happened."},"secret_expires_at":{"type":"string","format":"date-time","description":"When the client secret expires. Owners and admins are warned 14 days before."}},"required":["provider","client_id","client_secret"],"additionalProperties":false},{"type":"object","properties":{"provider":{"type":"string","enum":["microsoft"]},"client_id":{"type":"string","minLength":1,"maxLength":500,"pattern":"^\\S+$","description":"The app's client ID at the provider."},"client_secret":{"type":"string","minLength":1,"maxLength":1000,"description":"The app's client secret. Never returned."},"tenant_id":{"type":"string","pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9.-]{0,253})$","description":"The Directory (tenant) ID, for an app that's only for your own tenant. Leave it out for a multi-tenant app."},"redirect_uri":{"type":"string","maxLength":2000,"description":"A page on your own domain, registered with the provider, that forwards `code` and `state` to `coss_callback_url`. Google requires this for an external app, since it has to verify the redirect's domain as yours. Leave it out to use `coss_callback_url` directly."},"completion_url":{"type":"string","maxLength":2000,"description":"Where the browser lands after a consent that didn't name a `return_url`, with `coss_calendar` set to `connected`, `denied` or `invalid`. Leave it out for a plain page saying what happened."},"secret_expires_at":{"type":"string","format":"date-time","description":"When the client secret expires. Owners and admins are warned 14 days before."}},"required":["provider","client_id","client_secret"],"additionalProperties":false},{"type":"object","properties":{"provider":{"type":"string","enum":["zoom"]},"client_id":{"type":"string","minLength":1,"maxLength":500,"pattern":"^\\S+$","description":"The app's client ID at the provider."},"client_secret":{"type":"string","minLength":1,"maxLength":1000,"description":"The app's client secret. Never returned."},"webhook_secret":{"type":"string","minLength":1,"maxLength":1000,"description":"The Secret Token of your Zoom app, which signs its events at `zoom_event_url`. Never returned."},"redirect_uri":{"type":"string","maxLength":2000,"description":"A page on your own domain, registered with the provider, that forwards `code` and `state` to `coss_callback_url`. Google requires this for an external app, since it has to verify the redirect's domain as yours. Leave it out to use `coss_callback_url` directly."},"completion_url":{"type":"string","maxLength":2000,"description":"Where the browser lands after a consent that didn't name a `return_url`, with `coss_calendar` set to `connected`, `denied` or `invalid`. Leave it out for a plain page saying what happened."},"secret_expires_at":{"type":"string","format":"date-time","description":"When the client secret expires. Owners and admins are warned 14 days before."}},"required":["provider","client_id","client_secret"],"additionalProperties":false}],"examples":[{"provider":"google","client_id":"1234567890-abc.apps.googleusercontent.com","client_secret":"GOCSPX-abcdefghijklmnopqrstuvwxyz","redirect_uri":"https://example.com/oauth/google","completion_url":"https://example.com/calendar-connected"}]},"SchedulingOauthAppList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SchedulingOauthApp"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"scheduling.oauth_app","id":"calapp_01kd2m9a0b1c2d3e4f5g6h7j8m","provider":"google","client_id":"1234567890-abc.apps.googleusercontent.com","tenant_id":null,"redirect_uri":"https://example.com/oauth/google","coss_callback_url":"https://api.coss.com/scheduling/oauth/google/callback","completion_url":"https://example.com/calendar-connected","zoom_event_url":null,"scopes":["https://www.googleapis.com/auth/calendar.events.freebusy"],"status":"active","last_error_code":null,"last_error_at":null,"secret_expires_at":null,"verified_at":"2027-01-01T10:00:00.000Z","connections":12,"created_at":"2027-01-01T10:00:00.000Z","updated_at":"2027-01-01T10:00:00.000Z"}],"has_more":false}]},"UpdateOauthAppRequest":{"type":"object","properties":{"client_secret":{"type":"string","minLength":1,"maxLength":1000,"description":"A new client secret. It's tried on a connection before it replaces the old one."},"tenant_id":{"type":["string","null"],"pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9.-]{0,253})$","description":"The Directory (tenant) ID, for an app that's only for your own tenant. Leave it out for a multi-tenant app."},"webhook_secret":{"type":["string","null"],"minLength":1,"maxLength":1000,"description":"The Secret Token of your Zoom app, which signs its events at `zoom_event_url`. Never returned."},"redirect_uri":{"type":["string","null"],"maxLength":2000,"description":"A page on your own domain, registered with the provider, that forwards `code` and `state` to `coss_callback_url`. Google requires this for an external app, since it has to verify the redirect's domain as yours. Leave it out to use `coss_callback_url` directly."},"completion_url":{"type":["string","null"],"maxLength":2000,"description":"Where the browser lands after a consent that didn't name a `return_url`, with `coss_calendar` set to `connected`, `denied` or `invalid`. Leave it out for a plain page saying what happened."},"secret_expires_at":{"type":["string","null"],"format":"date-time","description":"When the client secret expires. Owners and admins are warned 14 days before."}},"additionalProperties":false,"examples":[{"client_secret":"GOCSPX-abcdefghijklmnopqrstuvwxyz"}]},"DeletedSchedulingOauthApp":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.oauth_app"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"scheduling.oauth_app","id":"calapp_01kd2m9a0b1c2d3e4f5g6h7j8m","deleted":true}]},"SetSimulatedBusyRequest":{"type":"object","properties":{"intervals":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"end":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]}},"required":["start","end"],"additionalProperties":false},"maxItems":500,"description":"The simulated calendar's busy times."}},"required":["intervals"],"additionalProperties":false,"examples":[{"intervals":[{"start":"2027-01-04T15:00:00.000Z","end":"2027-01-04T16:00:00.000Z"}]}]},"SchedulingSession":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.session"]},"id":{"type":"string"},"token":{"type":"string","description":"Shown only now. A bearer token for the client API."},"url":{"type":["string","null"],"description":"coss.com's hosted page, with the token in its fragment."},"expires_at":{"type":"string"}},"required":["object","id","token","url","expires_at"],"examples":[{"object":"scheduling.session","id":"schs_01kd2m9a0b1c2d3e4f5g6h7j8m","token":"cossch_abc123","url":"https://example.test/h/schs_01kd2m9a0b1c2d3e4f5g6h7j8m#cossch_abc123","expires_at":"2027-01-01T11:00:00.000Z"}]},"CreateSchedulingManagerSessionRequest":{"type":"object","properties":{"hosts":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000,"description":"The hosts this page can reach, by id or uid."},"host_filter":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Everyone matching these attributes, asked again on every request."},"expires_in":{"type":"integer","minimum":60,"maximum":86400,"description":"Seconds until it stops working. At most a day."},"read_only":{"type":"boolean"}},"additionalProperties":false,"examples":[{"host_filter":{"team":"cardiology"},"expires_in":3600}]},"CreateSchedulingHostSessionRequest":{"type":"object","properties":{"expires_in":{"type":"integer","minimum":60,"maximum":86400,"description":"Seconds until it stops working. At most a day."},"read_only":{"type":"boolean","description":"The host can look but not change anything."}},"additionalProperties":false,"examples":[{"expires_in":3600}]},"CreateSchedulingBookerSessionRequest":{"type":"object","properties":{"event_type":{"type":"string","description":"The event type's id or uid."},"host":{"type":"string","description":"Only this host (id or uid)."},"attributes":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50}]},"description":"Only offer times, and book, among pool hosts matching all of these. The browser can't see or change them."},"attendee":{"type":"object","properties":{"uid":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for this person, used to erase their data later."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Needed for coss.com to notify them. Can't contain a link."},"email":{"type":"string","maxLength":320,"format":"email","description":"Where coss.com emails them, if it does."},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"An E.164 number, for SMS reminders."},"time_zone":{"type":"string","minLength":1,"maxLength":64,"description":"Their IANA time zone. A series keeps their local time across clock changes.","examples":["America/New_York"]},"locale":{"type":"string","minLength":2,"maxLength":35,"description":"Their locale, such as `en-US`. Emails and texts about the booking are written in it when coss.com has it, otherwise in English, and guests get the same."}},"required":["time_zone"],"additionalProperties":false,"description":"Who's booking, if you already know: the browser then can't change it."},"expires_in":{"type":"integer","minimum":60,"maximum":86400,"description":"Seconds until it stops working. At most a day."}},"required":["event_type"],"additionalProperties":false,"examples":[{"event_type":"evtype_01kd2m9a0b1c2d3e4f5g6h7j8m","attendee":{"uid":"patient_77","name":"Sam Lee","time_zone":"UTC"}}]},"SchedulingSettings":{"type":"object","properties":{"object":{"type":"string","enum":["scheduling.settings"]},"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Sites allowed to embed coss.com's hosted pages and call the client API."},"brand_name":{"type":["string","null"],"description":"Your name on hosted pages and on emails sent from `email_from`. `null`: none set."},"accent_color":{"type":["string","null"],"description":"The accent color of hosted pages and emails sent from `email_from`, as `#RRGGBB`. `null`: the default."},"logo":{"type":["object","null"],"properties":{"content_type":{"type":"string","enum":["image/png","image/jpeg"],"description":"The image's type, checked from its bytes."},"width":{"type":"integer","description":"Width in pixels."},"height":{"type":"integer","description":"Height in pixels."},"data_url":{"type":"string","description":"The image, as a `data:` URL."}},"required":["content_type","width","height","data_url"],"description":"At the top of the hosted pages, and of emails sent from `email_from`."},"privacy_url":{"type":["string","null"],"description":"Your privacy policy, linked on a host's page beside what connecting a calendar does, once this environment has its own OAuth app and a `brand_name`."},"email_from":{"type":["string","null"],"description":"Sender of booking emails, on a verified domain."},"sms_from":{"type":["string","null"],"description":"Your approved number for SMS reminders. Without one, no SMS is sent."},"name_host_in_attendee_emails":{"type":"boolean","description":"Name the new host when telling an attendee their booking has one."},"host_reassignment":{"type":"string","enum":["off","eligible"],"description":"Whether hosts can give their own bookings to someone else from their page. `eligible` lets them, to anyone free who takes that event type."},"out_of_office_reasons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}},"required":["key","label"]},"description":"Reasons of your own for time away, on top of the preset ones."},"calendar_failure_mode":{"type":"string","enum":["hide","last_known"],"description":"When a host's calendar can't be read: `hide` stops offering them, `last_known` keeps offering their last known times."},"notifications":{"type":["object","null"],"additionalProperties":{"type":"object","properties":{"email_attendee":{"type":"boolean","description":"Email the attendee about this event."},"email_host":{"type":"boolean","description":"Email the host about this event."},"sms_attendee":{"type":"boolean","description":"Text the attendee about this event, if `sms_from` is set."}}},"description":"Per event, overriding the defaults."},"email_reply_to":{"type":["string","null"]},"reminders":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SchedulingReminder"},"description":"What goes out around a booking, unless an event type has its own. `null`: a reminder a day before, on the channels `notifications.reminder` chooses."}},"required":["object","allowed_origins","brand_name","accent_color","logo","privacy_url","email_from","sms_from","name_host_in_attendee_emails","host_reassignment","out_of_office_reasons","calendar_failure_mode","notifications","email_reply_to","reminders"],"examples":[{"object":"scheduling.settings","allowed_origins":["https://app.example.com"],"brand_name":"Acme Health","accent_color":null,"logo":null,"privacy_url":null,"email_from":"appointments@example.com","sms_from":null,"name_host_in_attendee_emails":false,"host_reassignment":"off","out_of_office_reasons":[],"calendar_failure_mode":"hide","notifications":{"reminder":{"sms_attendee":true}},"email_reply_to":null,"reminders":null}]},"UpdateSchedulingSettingsRequest":{"type":"object","properties":{"allowed_origins":{"type":"array","items":{"type":"string","maxLength":200},"maxItems":10,"description":"Sites allowed to embed coss.com's hosted pages and call the client API, as `https://host` origins."},"brand_name":{"type":["string","null"],"minLength":1,"maxLength":100,"description":"Your name on hosted pages and on emails sent from `email_from`. `null` removes it."},"accent_color":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","description":"The accent color as `#RRGGBB`. `null` restores the default."},"logo":{"type":["object","null"],"properties":{"content":{"type":"string","maxLength":266668,"description":"A PNG or JPEG's bytes, base64-encoded. 200 KB at most."}},"required":["content"],"additionalProperties":false,"description":"Your logo, a PNG or JPEG. `null` removes it."},"privacy_url":{"type":["string","null"],"maxLength":2000,"format":"uri","description":"Your privacy policy, as an https URL, for hosts connecting a calendar through your own OAuth app. `null` removes it."},"email_from":{"type":["string","null"],"maxLength":320,"format":"email","description":"Sender of booking emails, on a verified domain. `null`: coss.com's own address."},"sms_from":{"type":["string","null"],"pattern":"^\\+[1-9]\\d{6,14}$","description":"Your approved number for SMS reminders, in E.164. `null`: no SMS is sent."},"calendar_failure_mode":{"type":"string","enum":["hide","last_known"],"description":"When a host's calendar can't be read: `hide` stops offering them, `last_known` keeps offering their last known times."},"name_host_in_attendee_emails":{"type":"boolean","description":"Name the new host when telling an attendee their booking has one."},"host_reassignment":{"type":"string","enum":["off","eligible"],"description":"Whether hosts can give their own bookings to someone else from their page. `eligible` lets them, to anyone free who takes that event type."},"out_of_office_reasons":{"type":["array","null"],"items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,63}$","description":"One of `unspecified`, `vacation`, `travel`, `sick`, `public_holiday`, `parental_leave`, `training` and `other`, or a key from the settings' `out_of_office_reasons`. Only people who manage this host see it: never bookers, webhooks or calendars.","examples":["vacation"]},"label":{"type":"string","minLength":1,"maxLength":60}},"required":["key","label"],"additionalProperties":false},"maxItems":50,"description":"Reasons of your own, on top of the preset ones. Hosts and managers see them."},"notifications":{"type":["object","null"],"additionalProperties":{"type":"object","properties":{"email_attendee":{"type":"boolean","description":"Email the attendee about this event."},"email_host":{"type":"boolean","description":"Email the host about this event."},"sms_attendee":{"type":"boolean","description":"Text the attendee about this event, if `sms_from` is set."}},"additionalProperties":false},"description":"Per event (`confirmed`, `pending_approval`, `rescheduled`, `cancelled`, `declined`, `reminder`), overriding the defaults. `null` restores them."},"email_reply_to":{"type":["string","null"],"maxLength":320,"format":"email","description":"Where replies go, for emails from `email_from`."},"reminders":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SchedulingReminderInput"},"maxItems":10,"description":"What goes out around a booking, unless an event type has its own. `null` goes back to a reminder a day before."}},"additionalProperties":false,"examples":[{"brand_name":"Acme Health"}]},"TrackingSettings":{"type":"object","properties":{"object":{"type":"string","enum":["tracking_settings"]},"default":{"anyOf":[{"$ref":"#/components/schemas/TrackingRule"},{"type":"null"}],"description":"The environment's tracking default. `null`: none is set."},"categories":{"type":"array","items":{"$ref":"#/components/schemas/TrackingRule"},"description":"Category rules, by category name."}},"required":["object","default","categories"],"description":"Open and click tracking and one-click unsubscribe settings of the API key's environment. For each of `opens`, `clicks` and `unsubscribe`, a send's own `tracking` wins, then its category's rule, then `default` (the environment default; `null` when none is set), then off.","examples":[{"object":"tracking_settings","default":{"object":"tracking_rule","id":"etr_01k7c8k1d9w4x2b7n3m5q6r8st","category":null,"opens":true,"clicks":true,"unsubscribe":false,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"},"categories":[{"object":"tracking_rule","id":"etr_01k7c8m4q2f3e9v6t5r1n0p8yz","category":"password-reset","opens":false,"clicks":false,"unsubscribe":false,"created_at":"2026-01-16T10:00:00.000Z","updated_at":"2026-01-16T10:00:00.000Z"}]}]},"TrackingRule":{"type":"object","properties":{"object":{"type":"string","enum":["tracking_rule"]},"id":{"type":"string","examples":["etr_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"category":{"type":["string","null"],"description":"The category the rule applies to; `null` for the environment default."},"opens":{"type":"boolean","description":"Whether opens are tracked."},"clicks":{"type":"boolean","description":"Whether clicks are tracked."},"unsubscribe":{"type":"boolean","description":"Whether emails get one-click unsubscribe headers (only emails with a category and a single recipient)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","category","opens","clicks","unsubscribe","created_at","updated_at"],"description":"An environment's tracking default (`category: null`) or the rule for one category. Emails are fixed to the settings that applied when they were sent.","examples":[{"object":"tracking_rule","id":"etr_01k7c8m4q2f3e9v6t5r1n0p8yz","category":"password-reset","opens":false,"clicks":false,"unsubscribe":false,"created_at":"2026-01-16T10:00:00.000Z","updated_at":"2026-01-16T10:00:00.000Z"}]},"UpdateTrackingRuleRequest":{"type":"object","properties":{"opens":{"type":"boolean","description":"Track opens."},"clicks":{"type":"boolean","description":"Track clicks."},"unsubscribe":{"type":"boolean","description":"Add one-click unsubscribe headers to emails with a category and a single recipient."}},"additionalProperties":false,"description":"Fields left out keep their current value; a new rule starts with all off. A send's own `tracking` option still wins over the rule.","examples":[{"opens":false,"clicks":false}]},"DeletedTrackingRule":{"type":"object","properties":{"object":{"type":"string","enum":["tracking_rule"]},"id":{"type":"string"},"category":{"type":["string","null"]},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","category","deleted"],"examples":[{"object":"tracking_rule","id":"etr_01k7c8m4q2f3e9v6t5r1n0p8yz","category":"password-reset","deleted":true}]},"StorageSettings":{"type":"object","properties":{"object":{"type":"string","enum":["storage_settings"]},"content_storage":{"type":"string","enum":["store","discard"],"description":"`store` (the default) keeps each email's content (subject, body, headers, template variables, attachment filenames) for the email retention period. `discard` keeps it only until the email is sent, fails or is canceled; its metadata (addresses, tags, category, status, recipients, events) is kept as usual."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the setting last changed; `null` if it never did (content is stored)."}},"required":["object","content_storage","updated_at"],"description":"What coss.com keeps of the API key's environment's emails. Emails keep the setting that applied when they were sent.","examples":[{"object":"storage_settings","content_storage":"discard","updated_at":"2026-10-16T10:00:00.000Z"}]},"UpdateStorageSettingsRequest":{"type":"object","properties":{"content_storage":{"type":"string","enum":["store","discard"],"description":"`store` keeps emails' content; `discard` clears it once they are sent."}},"required":["content_storage"],"additionalProperties":false,"description":"Applies to emails sent from now on; emails already sent keep their setting.","examples":[{"content_storage":"discard"}]},"Contact":{"type":"object","properties":{"object":{"type":"string","enum":["contact"]},"id":{"type":"string"},"email":{"type":"string","description":"The contact's address. Unique in the environment, case-insensitively."},"first_name":{"type":["string","null"],"description":"Their first name. `null`: not set."},"last_name":{"type":["string","null"],"description":"Their last name. `null`: not set."},"status":{"type":"string","enum":["subscribed","unsubscribed","pending"],"description":"Consent to marketing email: `subscribed`, `unsubscribed` (never receives marketing email; transactional email is unaffected) or `pending` (waiting for a double opt-in confirmation)."},"properties":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"description":"Custom properties by key."},"source":{"type":"string","enum":["api","dashboard","import","preference_center","form"],"description":"How the contact was created."},"subscribed_at":{"type":["string","null"],"format":"date-time","description":"When it last became `subscribed`. `null`: it hasn't."},"unsubscribed_at":{"type":["string","null"],"format":"date-time","description":"When it became `unsubscribed`. `null` unless it is."},"confirmed_at":{"type":["string","null"],"format":"date-time","description":"When the contact confirmed a double opt-in."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","email","first_name","last_name","status","properties","source","subscribed_at","unsubscribed_at","confirmed_at","created_at","updated_at"],"examples":[{"object":"contact","id":"contact_01k7c8m4q2f3e9v6t5r1n0p8yz","email":"ada@example.com","first_name":"Ada","last_name":"Lovelace","status":"subscribed","properties":{"plan":"pro","seats":5},"source":"api","subscribed_at":"2026-10-10T12:00:00.000Z","unsubscribed_at":null,"confirmed_at":null,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"UpsertContactRequest":{"type":"object","properties":{"email":{"type":"string","description":"The contact's address. Display names are ignored; matching is case-insensitive.","examples":["ada@example.com"]},"first_name":{"type":["string","null"],"minLength":1,"maxLength":256,"description":"Their first name. `null` removes it."},"last_name":{"type":["string","null"],"minLength":1,"maxLength":256,"description":"Their last name. `null` removes it."},"properties":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Custom properties by key (define them first, see contact properties). Merged into the contact's existing properties; `null` removes one.","examples":[{"plan":"pro","seats":5}]},"status":{"type":"string","enum":["subscribed","unsubscribed"],"description":"Sets the contact's consent. Omitted, a new contact is `subscribed` and an existing one keeps its status."},"audience_ids":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Audiences to add the contact to (it stays in the others)."},"topics":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic's key."},"status":{"type":"string","enum":["opted_in","opted_out"],"description":"`opted_in` or `opted_out` of the topic."}},"required":["topic","status"],"additionalProperties":false},"maxItems":100,"description":"Choices per topic; topics left out keep the contact's choice."},"double_opt_in":{"type":"boolean","description":"Ask the contact to confirm first (default: the marketing settings' `double_opt_in_default`): a new or unsubscribed contact becomes `pending` and gets a confirmation email; it is `subscribed` once they click its link. Can't be combined with `status: \"subscribed\"`, nor can the default (pass `false` to subscribe directly)."}},"required":["email"],"additionalProperties":false,"examples":[{"email":"ada@example.com","first_name":"Ada","properties":{"plan":"pro"},"topics":[{"topic":"newsletter","status":"opted_in"}]}]},"ContactConfirmation":{"type":"object","properties":{"object":{"type":"string","enum":["contact_confirmation"]},"contact_id":{"type":"string","description":"The contact's id."},"status":{"type":"string","enum":["sent","cooldown","limit_reached","not_pending"],"description":"`sent`; `cooldown` (one confirmation per contact per day); `limit_reached` (three were sent and none confirmed); `not_pending` (the contact isn't waiting to confirm)."}},"required":["object","contact_id","status"],"examples":[{"object":"contact_confirmation","contact_id":"contact_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"sent"}]},"PreferenceLinks":{"type":"object","properties":{"object":{"type":"string","enum":["preference_links"]},"contact_id":{"type":"string","description":"The contact's id."},"preferences_url":{"type":"string","description":"The contact's preference center."},"unsubscribe_url":{"type":"string","description":"A one-button unsubscribe page."}},"required":["object","contact_id","preferences_url","unsubscribe_url"],"examples":[{"object":"preference_links","contact_id":"contact_01k7c8m4q2f3e9v6t5r1n0p8yz","preferences_url":"https://track.cosslinks.com/t/u/aXyZ…","unsubscribe_url":"https://track.cosslinks.com/t/u/aXyZ…/unsubscribe"}]},"CreatePreferenceLinksRequest":{"type":"object","properties":{"topic":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic your email is about: its unsubscribe link leaves just that topic."}},"additionalProperties":false,"examples":[{"topic":"newsletter"}]},"ContactList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"contact","id":"contact_01k7c8m4q2f3e9v6t5r1n0p8yz","email":"ada@example.com","first_name":"Ada","last_name":"Lovelace","status":"subscribed","properties":{"plan":"pro","seats":5},"source":"api","subscribed_at":"2026-10-10T12:00:00.000Z","unsubscribed_at":null,"confirmed_at":null,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"ContactImport":{"type":"object","properties":{"object":{"type":"string","enum":["contact_import"]},"created":{"type":"integer","description":"Contacts created."},"updated":{"type":"integer","description":"Existing contacts updated."},"kept_unsubscribed":{"type":"integer","description":"Existing contacts the import marked `subscribed` that stay `unsubscribed`: an import never re-subscribes anyone."},"invalid":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"The entry's position in `contacts`, from 0."},"email":{"type":"string","description":"The address it gave."},"message":{"type":"string","description":"Why it was refused."}},"required":["index","email","message"]},"description":"Entries that were refused. The rest of the import still went through."}},"required":["object","created","updated","kept_unsubscribed","invalid"],"examples":[{"object":"contact_import","created":1,"updated":1,"kept_unsubscribed":0,"invalid":[{"index":2,"email":"not-an-address","message":"Must be an email address."}]}]},"ImportContactsRequest":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","description":"The contact's address (validated on its own)."},"first_name":{"type":["string","null"],"description":"Their first name."},"last_name":{"type":["string","null"],"description":"Their last name."},"properties":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Custom properties by key, checked against their definitions."},"status":{"type":"string","description":"`subscribed` or `unsubscribed` (anything else, like an export's `pending`, is reported in `invalid`). Omitted, a new contact is `subscribed` and an existing one keeps its status."}},"required":["email"],"additionalProperties":false},"minItems":1,"maxItems":1000,"description":"The contacts to create or update, at most 1,000."},"audience_id":{"type":"string","description":"Adds every imported contact to this audience."}},"required":["contacts"],"additionalProperties":false,"examples":[{"contacts":[{"email":"ada@example.com","first_name":"Ada","properties":{"plan":"pro"}},{"email":"grace@example.com","status":"unsubscribed"}]}]},"UpdateContactRequest":{"type":"object","properties":{"first_name":{"type":["string","null"],"minLength":1,"maxLength":256,"description":"Their first name. `null` removes it."},"last_name":{"type":["string","null"],"minLength":1,"maxLength":256,"description":"Their last name. `null` removes it."},"properties":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Custom properties by key (define them first, see contact properties). Merged into the contact's existing properties; `null` removes one.","examples":[{"plan":"pro","seats":5}]},"status":{"type":"string","enum":["subscribed","unsubscribed"],"description":"Sets the contact's consent. Omitted, a new contact is `subscribed` and an existing one keeps its status."},"topics":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic's key."},"status":{"type":"string","enum":["opted_in","opted_out"],"description":"`opted_in` or `opted_out` of the topic."}},"required":["topic","status"],"additionalProperties":false},"maxItems":100}},"additionalProperties":false,"examples":[{"last_name":"Byron","properties":{"seats":null}}]},"DeletedContact":{"type":"object","properties":{"object":{"type":"string","enum":["contact"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"contact","id":"contact_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"ContactTopics":{"type":"object","properties":{"object":{"type":"string","enum":["contact_topics"]},"contact_id":{"type":"string","description":"The contact's id."},"topics":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string","description":"The topic's key."},"name":{"type":"string","description":"The topic's name."},"subscribed":{"type":"boolean","description":"Whether emails about the topic reach the contact (its choice, else the topic's default; an unsubscribed contact gets no marketing email at all)."},"choice":{"type":["string","null"],"enum":["opted_in","opted_out",null],"description":"The contact's explicit choice; `null`: the topic's default applies."}},"required":["topic","name","subscribed","choice"]},"description":"Every topic of the environment, with this contact's standing."}},"required":["object","contact_id","topics"],"examples":[{"object":"contact_topics","contact_id":"contact_01k7c8m4q2f3e9v6t5r1n0p8yz","topics":[{"topic":"newsletter","name":"Newsletter","subscribed":true,"choice":null},{"topic":"product","name":"Product updates","subscribed":false,"choice":"opted_out"}]}]},"UpdateContactTopicsRequest":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic's key."},"status":{"type":"string","enum":["opted_in","opted_out"],"description":"`opted_in` or `opted_out` of the topic."}},"required":["topic","status"],"additionalProperties":false},"minItems":1,"maxItems":100,"description":"The contact's choices per topic. Topics not listed keep theirs."}},"required":["topics"],"additionalProperties":false,"examples":[{"topics":[{"topic":"product","status":"opted_out"}]}]},"ContactPropertyList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactProperty"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"contact_property","id":"cprop_01k7c8m4q2f3e9v6t5r1n0p8yz","key":"plan","type":"string","fallback":"free","created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"ContactProperty":{"type":"object","properties":{"object":{"type":"string","enum":["contact_property"]},"id":{"type":"string"},"key":{"type":"string","description":"How contacts and templates name it (`{{{contact.<key>}}}`). Can't change."},"type":{"type":"string","enum":["string","number","boolean","date"],"description":"`date` values are ISO 8601 strings."},"fallback":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"description":"Used in templates for contacts without a value."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","key","type","fallback","created_at","updated_at"],"examples":[{"object":"contact_property","id":"cprop_01k7c8m4q2f3e9v6t5r1n0p8yz","key":"plan","type":"string","fallback":"free","created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"CreateContactPropertyRequest":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,49}$","description":"How contacts and templates name it. Lower-case letters, digits and `_`, starting with a letter. Can't change."},"type":{"type":"string","enum":["string","number","boolean","date"],"description":"What values it takes. `date` values are ISO 8601 strings. Can't change."},"fallback":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}],"description":"Used in templates for contacts without a value."}},"required":["key","type"],"additionalProperties":false,"examples":[{"key":"plan","type":"string","fallback":"free"}]},"UpdateContactPropertyRequest":{"type":"object","properties":{"fallback":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"null"}],"description":"Used in templates for contacts without a value. `null` removes it."}},"required":["fallback"],"additionalProperties":false,"examples":[{"fallback":"starter"}]},"DeletedContactProperty":{"type":"object","properties":{"object":{"type":"string","enum":["contact_property"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"contact_property","id":"cprop_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"BroadcastList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Broadcast"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"broadcast","id":"bcast_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"October newsletter","status":"sent","audience_id":null,"segment_id":"seg_01k7c8m4q2f3e9v6t5r1n0p8yz","topic":"newsletter","from":"Acme <news@acme.com>","reply_to":[],"subject":"What's new, {{{contact.first_name|there}}}","preview_text":null,"html":"<p>Hi {{{contact.first_name|there}}},</p>","text":null,"tracking":{"opens":true,"clicks":true},"rate_per_second":null,"scheduled_at":"2026-10-20T09:00:00.000Z","started_at":"2026-10-20T09:00:01.000Z","completed_at":"2026-10-20T09:12:40.000Z","canceled_at":null,"recipients_estimated":1200,"pause_reason":null,"error":null,"stats":{"recipients":1200,"sent":1200,"delivered":1180,"bounced":6,"complained":1,"failed":0,"opened":540,"clicked":120,"unsubscribed":4},"created_at":"2026-10-15T12:00:00.000Z","updated_at":"2026-10-20T09:12:40.000Z"}],"has_more":false}]},"Broadcast":{"type":"object","properties":{"object":{"type":"string","enum":["broadcast"]},"id":{"type":"string"},"name":{"type":"string","description":"Shown only to you."},"status":{"type":"string","enum":["draft","scheduled","sending","paused","sent","canceled","failed"],"description":"`draft` (editable), `scheduled`, `sending`, `paused` (see `pause_reason`), `sent`, `canceled`, or `failed` (see `error`)."},"audience_id":{"type":["string","null"],"description":"The audience it goes to. `null`: a segment."},"segment_id":{"type":["string","null"],"description":"The segment it goes to. `null`: an audience."},"topic":{"type":["string","null"],"description":"The topic it's about (its key), and its emails' `category`. `null`: none."},"from":{"type":"string","description":"Who it's sent from."},"reply_to":{"type":"array","items":{"type":"string"},"description":"Addresses replies go to."},"subject":{"type":"string","description":"The subject, before contact fields are filled in."},"preview_text":{"type":["string","null"],"description":"The inbox preview line. `null`: none."},"html":{"type":["string","null"],"description":"The HTML part, before contact fields are filled in. `null`: text only."},"text":{"type":["string","null"],"description":"The plain text part. `null`: HTML only."},"tracking":{"type":"object","properties":{"opens":{"type":"boolean","description":"Whether opens are tracked."},"clicks":{"type":"boolean","description":"Whether clicks are tracked."}},"required":["opens","clicks"],"description":"Which opens and clicks are tracked."},"rate_per_second":{"type":["integer","null"],"description":"Recipients per second. `null`: the plan's marketing rate."},"scheduled_at":{"type":["string","null"],"format":"date-time","description":"When it's set to start. `null`: not scheduled."},"started_at":{"type":["string","null"],"format":"date-time","description":"When sending started. `null`: it hasn't."},"completed_at":{"type":["string","null"],"format":"date-time","description":"When it finished. `null`: it hasn't."},"canceled_at":{"type":["string","null"],"format":"date-time","description":"When it was canceled. `null`: it wasn't."},"recipients_estimated":{"type":["integer","null"],"description":"How many contacts it would reach, counted when it started."},"pause_reason":{"type":["string","null"],"description":"Why a paused broadcast waits: `paused` (by you), `billing_hold`, `budget_exceeded`, `usage_limit`, `marketing_paused`, `account_suspended`, `sending_paused`."},"error":{"type":["object","null"],"properties":{"code":{"type":"string","description":"Machine-readable reason."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["code","message"],"description":"Why it `failed`, such as `target_unavailable` when its audience, segment or topic was deleted while sending. `null`: it didn't."},"stats":{"$ref":"#/components/schemas/BroadcastStats"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","status","audience_id","segment_id","topic","from","reply_to","subject","preview_text","html","text","tracking","rate_per_second","scheduled_at","started_at","completed_at","canceled_at","recipients_estimated","pause_reason","error","stats","created_at","updated_at"],"examples":[{"object":"broadcast","id":"bcast_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"October newsletter","status":"sent","audience_id":null,"segment_id":"seg_01k7c8m4q2f3e9v6t5r1n0p8yz","topic":"newsletter","from":"Acme <news@acme.com>","reply_to":[],"subject":"What's new, {{{contact.first_name|there}}}","preview_text":null,"html":"<p>Hi {{{contact.first_name|there}}},</p>","text":null,"tracking":{"opens":true,"clicks":true},"rate_per_second":null,"scheduled_at":"2026-10-20T09:00:00.000Z","started_at":"2026-10-20T09:00:01.000Z","completed_at":"2026-10-20T09:12:40.000Z","canceled_at":null,"recipients_estimated":1200,"pause_reason":null,"error":null,"stats":{"recipients":1200,"sent":1200,"delivered":1180,"bounced":6,"complained":1,"failed":0,"opened":540,"clicked":120,"unsubscribed":4},"created_at":"2026-10-15T12:00:00.000Z","updated_at":"2026-10-20T09:12:40.000Z"}]},"CreateBroadcastRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Shown only to you."},"audience_id":{"type":"string","description":"Send to this audience…"},"segment_id":{"type":"string","description":"…or to this segment (one of the two)."},"topic":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic the broadcast is about (its key): only contacts it reaches get it, and its unsubscribe link leaves just that topic. It is the emails' `category`."},"from":{"type":"string","examples":["Acme <news@acme.com>"]},"reply_to":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Addresses replies go to."},"subject":{"type":"string","minLength":1,"maxLength":998,"description":"May use `{{{contact.<key>|fallback}}}` (e.g. `{{{contact.first_name|there}}}`)."},"preview_text":{"type":"string","maxLength":500,"description":"The inbox preview line (a hidden preheader at the start of the HTML)."},"html":{"type":"string","maxLength":1000000,"description":"`{{{contact.<key>|fallback}}}` for contact fields and properties (escaped), and `{{{unsubscribe_url}}}`, `{{{preferences_url}}}`, `{{{mailing_address}}}`; a footer with the postal address and an unsubscribe link is added unless they are there."},"text":{"type":"string","maxLength":1000000,"description":"The plain text part. Takes the same placeholders as `html`."},"tracking":{"type":"object","properties":{"opens":{"type":"boolean","description":"Track opens with a pixel."},"clicks":{"type":"boolean","description":"Track clicks by rewriting links."}},"additionalProperties":false,"description":"Which opens and clicks are tracked."},"rate_per_second":{"type":"integer","minimum":1,"maximum":1000,"description":"Recipients per second, at most the plan's marketing rate (the default)."},"send":{"type":"boolean","description":"Start sending right away."},"scheduled_at":{"type":"string","format":"date-time","description":"Start sending at this time (ISO 8601 with an offset, at most 30 days ahead)."}},"required":["name","from","subject"],"additionalProperties":false,"examples":[{"name":"October newsletter","segment_id":"seg_01k7c8m4q2f3e9v6t5r1n0p8yz","topic":"newsletter","from":"Acme <news@acme.com>","subject":"What's new, {{{contact.first_name|there}}}","html":"<p>Hi {{{contact.first_name|there}}},</p><p>…</p><p><a href=\"{{{unsubscribe_url}}}\">Unsubscribe</a></p>","scheduled_at":"2026-10-20T09:00:00Z"}]},"UpdateBroadcastRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Shown only to you."},"audience_id":{"type":["string","null"],"description":"Send to this audience. `null` clears it."},"segment_id":{"type":["string","null"],"description":"Send to this segment. `null` clears it."},"topic":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic it's about (its key). `null` clears it."},"from":{"type":"string","examples":["Acme <news@acme.com>"]},"reply_to":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Addresses replies go to."},"subject":{"type":"string","minLength":1,"maxLength":998,"description":"May use `{{{contact.<key>|fallback}}}` (e.g. `{{{contact.first_name|there}}}`)."},"preview_text":{"type":["string","null"],"maxLength":500,"description":"The inbox preview line. `null` removes it."},"html":{"type":["string","null"],"maxLength":1000000,"description":"The HTML part. `null` removes it, if `text` remains."},"text":{"type":["string","null"],"maxLength":1000000,"description":"The plain text part. `null` removes it, if `html` remains."},"tracking":{"type":"object","properties":{"opens":{"type":"boolean","description":"Track opens with a pixel."},"clicks":{"type":"boolean","description":"Track clicks by rewriting links."}},"additionalProperties":false,"description":"Which opens and clicks are tracked."},"rate_per_second":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Recipients per second. `null`: the plan's marketing rate."}},"additionalProperties":false,"examples":[{"subject":"Our October news"}]},"DeletedBroadcast":{"type":"object","properties":{"object":{"type":"string","enum":["broadcast"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"broadcast","id":"bcast_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"SendBroadcastRequest":{"type":"object","properties":{"scheduled_at":{"type":"string","format":"date-time","description":"Omit to start right away."}},"additionalProperties":false,"examples":[{"scheduled_at":"2026-10-20T09:00:00Z"}]},"BroadcastTest":{"type":"object","properties":{"object":{"type":"string","enum":["broadcast_test"]},"email_ids":{"type":"array","items":{"type":"string"},"description":"The ids of the test emails."}},"required":["object","email_ids"],"examples":[{"object":"broadcast_test","email_ids":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]}]},"TestBroadcastRequest":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":5,"description":"Who gets the test, at most 5 addresses."},"contact":{"type":"string","description":"A contact (id or address) whose values fill the template; default: fallbacks."}},"required":["to"],"additionalProperties":false,"examples":[{"to":["me@acme.com"]}]},"BroadcastEmailList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Email"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"]},"AudienceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Audience"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"audience","id":"aud_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Beta testers","contact_count":42,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"Audience":{"type":"object","properties":{"object":{"type":"string","enum":["audience"]},"id":{"type":"string"},"name":{"type":"string","description":"Your name for the list, unique in the environment."},"contact_count":{"type":"integer","description":"Members, whatever their status."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","contact_count","created_at","updated_at"],"examples":[{"object":"audience","id":"aud_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Beta testers","contact_count":42,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"CreateAudienceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the list, unique in the environment."}},"required":["name"],"additionalProperties":false,"examples":[{"name":"Beta testers"}]},"UpdateAudienceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the list, unique in the environment."}},"required":["name"],"additionalProperties":false,"examples":[{"name":"Early access"}]},"DeletedAudience":{"type":"object","properties":{"object":{"type":"string","enum":["audience"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"audience","id":"aud_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"AudienceContactsAdded":{"type":"object","properties":{"object":{"type":"string","enum":["audience_contacts"]},"added":{"type":"integer","description":"Contacts newly added."},"existing":{"type":"integer","description":"Contacts that were already members."},"missing":{"type":"array","items":{"type":"string"},"description":"Ids or addresses of no contact."}},"required":["object","added","existing","missing"],"examples":[{"object":"audience_contacts","added":1,"existing":0,"missing":[]}]},"AddAudienceContactsRequest":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000,"description":"Contact ids or addresses of existing contacts."}},"required":["contacts"],"additionalProperties":false,"examples":[{"contacts":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz","grace@example.com"]}]},"SegmentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"segment","id":"seg_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Pro customers","filter":{"version":1,"match":"all","conditions":[{"field":"property","key":"plan","op":"eq","value":"pro"},{"match":"any","conditions":[{"field":"email","op":"ends_with","value":"@acme.com"},{"field":"audience","op":"in","audience_id":"aud_01k7c8m4q2f3e9v6t5r1n0p8yz"}]}]},"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"Segment":{"type":"object","properties":{"object":{"type":"string","enum":["segment"]},"id":{"type":"string"},"name":{"type":"string","description":"Your name for the segment, unique in the environment."},"filter":{"$ref":"#/components/schemas/SegmentFilter"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","filter","created_at","updated_at"],"examples":[{"object":"segment","id":"seg_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Pro customers","filter":{"version":1,"match":"all","conditions":[{"field":"property","key":"plan","op":"eq","value":"pro"},{"match":"any","conditions":[{"field":"email","op":"ends_with","value":"@acme.com"},{"field":"audience","op":"in","audience_id":"aud_01k7c8m4q2f3e9v6t5r1n0p8yz"}]}]},"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"SegmentFilter":{"type":"object","properties":{"version":{"type":"number","enum":[1],"description":"The filter's format. Always 1."},"match":{"type":"string","enum":["all","any"],"description":"`all`: every condition must hold; `any`: one is enough."},"conditions":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"field":{"type":"string","enum":["property"]},"key":{"type":"string","description":"The custom property to test."},"op":{"type":"string","enum":["eq","neq","in","not_in","gt","gte","lt","lte","contains","starts_with","exists","not_exists"],"description":"How to compare: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, or `exists` and `not_exists`, which take no value."},"value":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},"minItems":1,"maxItems":100}],"description":"A list for `in`/`not_in`; none for `exists`/`not_exists`."}},"required":["field","key","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["email"]},"op":{"type":"string","enum":["eq","ends_with","contains"],"description":"How to compare the contact's address."},"value":{"type":"string","minLength":1,"maxLength":254,"description":"What to compare it with."}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["audience"]},"op":{"type":"string","enum":["in","not_in"],"description":"Whether the contact is in the audience."},"audience_id":{"type":"string","description":"The audience's id."}},"required":["field","op","audience_id"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["topic"]},"op":{"type":"string","enum":["subscribed","not_subscribed"],"description":"Whether emails about the topic reach the contact."},"topic":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic's key."}},"required":["field","op","topic"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["created_at"]},"op":{"type":"string","enum":["before","after","within_days"],"description":"`before` or `after` a time, or created `within_days` the last days."},"value":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer","minimum":1,"maximum":3650}],"description":"A timestamp for `before`/`after`, a number of days for `within_days`."}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"match":{"type":"string","enum":["all","any"],"description":"`all`: every condition must hold; `any`: one is enough."},"conditions":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"field":{"type":"string","enum":["property"]},"key":{"type":"string","description":"The custom property to test."},"op":{"type":"string","enum":["eq","neq","in","not_in","gt","gte","lt","lte","contains","starts_with","exists","not_exists"],"description":"How to compare: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, or `exists` and `not_exists`, which take no value."},"value":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},"minItems":1,"maxItems":100}],"description":"A list for `in`/`not_in`; none for `exists`/`not_exists`."}},"required":["field","key","op"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["email"]},"op":{"type":"string","enum":["eq","ends_with","contains"],"description":"How to compare the contact's address."},"value":{"type":"string","minLength":1,"maxLength":254,"description":"What to compare it with."}},"required":["field","op","value"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["audience"]},"op":{"type":"string","enum":["in","not_in"],"description":"Whether the contact is in the audience."},"audience_id":{"type":"string","description":"The audience's id."}},"required":["field","op","audience_id"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["topic"]},"op":{"type":"string","enum":["subscribed","not_subscribed"],"description":"Whether emails about the topic reach the contact."},"topic":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The topic's key."}},"required":["field","op","topic"],"additionalProperties":false},{"type":"object","properties":{"field":{"type":"string","enum":["created_at"]},"op":{"type":"string","enum":["before","after","within_days"],"description":"`before` or `after` a time, or created `within_days` the last days."},"value":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer","minimum":1,"maximum":3650}],"description":"A timestamp for `before`/`after`, a number of days for `within_days`."}},"required":["field","op","value"],"additionalProperties":false}]},"minItems":1,"description":"The group's conditions."}},"required":["match","conditions"],"additionalProperties":false}]},"minItems":1,"description":"Conditions, or `{ match, conditions }` groups of them. At most 20 in all."}},"required":["version","match","conditions"],"additionalProperties":false,"description":"Which contacts belong to the segment. Conditions on `property` (custom properties), `email`, `audience` membership, `topic` subscription and `created_at`; one level of nested `{ match, conditions }` groups."},"CreateSegmentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the segment, unique in the environment."},"filter":{"$ref":"#/components/schemas/SegmentFilter"}},"required":["name","filter"],"additionalProperties":false,"examples":[{"name":"Pro customers","filter":{"version":1,"match":"all","conditions":[{"field":"property","key":"plan","op":"eq","value":"pro"},{"match":"any","conditions":[{"field":"email","op":"ends_with","value":"@acme.com"},{"field":"audience","op":"in","audience_id":"aud_01k7c8m4q2f3e9v6t5r1n0p8yz"}]}]}}]},"UpdateSegmentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Your name for the segment, unique in the environment."},"filter":{"$ref":"#/components/schemas/SegmentFilter"}},"additionalProperties":false,"examples":[{"name":"Pro and Scale customers"}]},"DeletedSegment":{"type":"object","properties":{"object":{"type":"string","enum":["segment"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"segment","id":"seg_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"TopicList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Topic"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"topic","id":"topic_01k7c8m4q2f3e9v6t5r1n0p8yz","key":"newsletter","name":"Newsletter","description":"Monthly product news.","default_subscription":"opt_in","visibility":"public","position":0,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"Topic":{"type":"object","properties":{"object":{"type":"string","enum":["topic"]},"id":{"type":"string"},"key":{"type":"string","description":"The `category` of the emails about this topic. Can't change."},"name":{"type":"string","description":"Shown in the preference center."},"description":{"type":["string","null"],"description":"Shown in the preference center under its name. `null`: none."},"default_subscription":{"type":"string","enum":["opt_in","opt_out"],"description":"`opt_in`: every subscribed contact gets the topic's emails unless they opt out. `opt_out`: only contacts who opted in do."},"visibility":{"type":"string","enum":["public","private"],"description":"`private` topics never show in the preference center."},"position":{"type":"integer","description":"Order in the preference center (ascending)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","key","name","description","default_subscription","visibility","position","created_at","updated_at"],"examples":[{"object":"topic","id":"topic_01k7c8m4q2f3e9v6t5r1n0p8yz","key":"newsletter","name":"Newsletter","description":"Monthly product news.","default_subscription":"opt_in","visibility":"public","position":0,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"CreateTopicRequest":{"type":"object","properties":{"key":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The `category` of the emails about this topic. Can't change."},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Shown in the preference center."},"description":{"type":["string","null"],"maxLength":500,"description":"Shown in the preference center under its name. `null`: none."},"default_subscription":{"type":"string","enum":["opt_in","opt_out"],"description":"`opt_in`: every subscribed contact gets the topic's emails unless they opt out. `opt_out`: only contacts who opted in do."},"visibility":{"type":"string","enum":["public","private"],"description":"`private` topics never show in the preference center (default `public`)."},"position":{"type":"integer","minimum":0,"maximum":1000,"description":"Order in the preference center (ascending)."}},"required":["key","name","default_subscription"],"additionalProperties":false,"examples":[{"key":"newsletter","name":"Newsletter","default_subscription":"opt_in"}]},"UpdateTopicRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Shown in the preference center."},"description":{"type":["string","null"],"maxLength":500,"description":"Shown in the preference center under its name. `null`: none."},"default_subscription":{"type":"string","enum":["opt_in","opt_out"],"description":"`opt_in`: every subscribed contact gets the topic's emails unless they opt out. `opt_out`: only contacts who opted in do."},"visibility":{"type":"string","enum":["public","private"],"description":"`private` topics never show in the preference center (default `public`)."},"position":{"type":"integer","minimum":0,"maximum":1000,"description":"Order in the preference center (ascending)."}},"additionalProperties":false,"examples":[{"visibility":"private"}]},"DeletedTopic":{"type":"object","properties":{"object":{"type":"string","enum":["topic"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"topic","id":"topic_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"MarketingSettings":{"type":"object","properties":{"object":{"type":"string","enum":["marketing_settings"]},"display_name":{"type":["string","null"],"description":"The sender's name in the preference center (default: the organization's)."},"mailing_address":{"type":["string","null"],"description":"The postal address every marketing email carries (CAN-SPAM). Marketing emails can't be sent without one."},"double_opt_in_default":{"type":"boolean","description":"Whether contacts upserted without `double_opt_in` must confirm first."},"confirmation_from":{"type":["string","null"],"description":"The sender of confirmation emails (a verified domain's address for live keys)."},"confirmation_subject":{"type":["string","null"],"description":"`null`: coss.com's default."},"confirmation_html":{"type":["string","null"],"description":"`null`: coss.com's default. Must contain `{{{confirmation_url}}}`."},"confirmation_text":{"type":["string","null"],"description":"`null`: coss.com's default. Must contain `{{{confirmation_url}}}`."},"confirmed_redirect_url":{"type":["string","null"],"description":"Where confirming sends the contact (https); `null`: a coss.com confirmation page."}},"required":["object","display_name","mailing_address","double_opt_in_default","confirmation_from","confirmation_subject","confirmation_html","confirmation_text","confirmed_redirect_url"],"examples":[{"object":"marketing_settings","display_name":"Acme","mailing_address":"Acme Inc., 548 Market St, San Francisco, CA 94104, USA","double_opt_in_default":true,"confirmation_from":"Acme <news@acme.com>","confirmation_subject":null,"confirmation_html":null,"confirmation_text":null,"confirmed_redirect_url":"https://acme.com/welcome"}]},"UpdateMarketingSettingsRequest":{"type":"object","properties":{"display_name":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"The sender's name in the preference center. `null`: the organization's."},"mailing_address":{"type":["string","null"],"minLength":1,"maxLength":500,"description":"The postal address every marketing email carries (CAN-SPAM). Marketing emails can't be sent without one."},"double_opt_in_default":{"type":"boolean","description":"Whether contacts upserted without `double_opt_in` must confirm first."},"confirmation_from":{"type":["string","null"],"description":"The sender of confirmation emails (a verified domain's address for live keys)."},"confirmation_subject":{"type":["string","null"],"minLength":1,"maxLength":998,"description":"`null`: coss.com's default."},"confirmation_html":{"type":["string","null"],"maxLength":200000,"description":"`null`: coss.com's default. Must contain `{{{confirmation_url}}}`."},"confirmation_text":{"type":["string","null"],"maxLength":200000,"description":"`null`: coss.com's default. Must contain `{{{confirmation_url}}}`."},"confirmed_redirect_url":{"type":["string","null"],"maxLength":2000,"format":"uri","description":"Where a confirmed contact is sent, an https URL. `null`: coss.com's own page."}},"additionalProperties":false,"examples":[{"mailing_address":"Acme Inc., 548 Market St, San Francisco, CA 94104, USA"}]},"Reputation":{"type":"object","properties":{"object":{"type":"string","enum":["reputation"]},"status":{"type":"string","enum":["good","warning","suspended"],"description":"`good`, `warning` (a rate is approaching the suspension threshold) or `suspended` (live sending is refused until coss.com support reinstates the organization)."},"reason":{"type":["string","null"],"description":"The trigger behind a `warning` or `suspended` status.","example":"complaint_rate"},"status_changed_at":{"type":["string","null"],"format":"date-time","description":"When `status` last changed. `null`: it never has."},"evaluated_at":{"type":["string","null"],"format":"date-time","description":"When the checks below were computed; `null` before the first evaluation."},"window":{"type":["object","null"],"properties":{"start":{"type":"string","format":"date-time","description":"When the period starts."},"end":{"type":"string","format":"date-time","description":"When the period ends."}},"required":["start","end"],"description":"The period the checks cover (live environments only)."},"checks":{"type":"array","items":{"$ref":"#/components/schemas/ReputationCheck"},"description":"The measurements behind `status`."},"marketing":{"$ref":"#/components/schemas/MarketingStanding"}},"required":["object","status","reason","status_changed_at","evaluated_at","window","checks","marketing"]},"LogList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Log"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"log","id":"log_01k7c8m4q2f3e9v6t5r1n0p8yz","occurred_at":"2026-01-15T09:30:00.000Z","source":"api","level":"info","type":"api.request","message":"POST /v1/emails 202","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz","api_key_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","method":"POST","path":"/https/api.coss.com/v1/emails","route":"/v1/emails","status_code":202,"duration_ms":48,"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0","error_code":null,"resource_type":"email","resource_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","recipient":null,"attributes":{"request":{"body":{"from":"hello@example.com","to":["user@example.com"],"subject":"Hi"}},"response":{"body":{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz"}}}}],"has_more":false}]},"Log":{"type":"object","properties":{"object":{"type":"string","enum":["log"]},"id":{"type":"string","examples":["log_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"source":{"$ref":"#/components/schemas/LogSource"},"level":{"$ref":"#/components/schemas/LogLevel"},"type":{"type":"string","description":"`api.request`, `webhook.attempt`, `webhook.forward` (an event `coss listen` forwarded), or an email event type such as `email.delivered`."},"message":{"type":"string","description":"A one-line summary."},"request_id":{"type":["string","null"],"description":"The `X-Request-Id` of the API request this line belongs to."},"api_key_id":{"type":["string","null"],"description":"The API key that made the request. `null`: not an API request."},"method":{"type":["string","null"],"description":"The HTTP method. `null`: not an HTTP line."},"path":{"type":["string","null"],"description":"The request's path. `null`: not an API request."},"route":{"type":["string","null"],"description":"The matched route, e.g. `/v1/emails/:id`."},"status_code":{"type":["integer","null"],"description":"The API response status, or the webhook endpoint's response status."},"duration_ms":{"type":["integer","null"],"description":"How long it took, in milliseconds. `null`: not timed."},"client_ip":{"type":["string","null"],"description":"The caller's address. `null`: not an API request."},"user_agent":{"type":["string","null"],"description":"The caller's `User-Agent`. `null`: not sent."},"error_code":{"type":["string","null"],"description":"The error's `code`. `null`: no error."},"resource_type":{"type":["string","null"],"description":"What the line is about: `email`, `domain`, `webhook_endpoint`…"},"resource_id":{"type":["string","null"],"description":"The id of what it's about. `null`: nothing in particular."},"recipient":{"type":["string","null"],"description":"The recipient an email event is about. `null`: none."},"attributes":{"type":"object","additionalProperties":{},"description":"Details: redacted request and response bodies for API requests (secrets, attachment contents and long strings are never stored), event data for emails and webhooks."}},"required":["object","id","occurred_at","source","level","type","message","request_id","api_key_id","method","path","route","status_code","duration_ms","client_ip","user_agent","error_code","resource_type","resource_id","recipient","attributes"],"examples":[{"object":"log","id":"log_01k7c8m4q2f3e9v6t5r1n0p8yz","occurred_at":"2026-01-15T09:30:00.000Z","source":"api","level":"info","type":"api.request","message":"POST /v1/emails 202","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz","api_key_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","method":"POST","path":"/https/api.coss.com/v1/emails","route":"/v1/emails","status_code":202,"duration_ms":48,"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0","error_code":null,"resource_type":"email","resource_id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz","recipient":null,"attributes":{"request":{"body":{"from":"hello@example.com","to":["user@example.com"],"subject":"Hi"}},"response":{"body":{"object":"email","id":"email_01k7c8m4q2f3e9v6t5r1n0p8yz"}}}}]},"LogSource":{"type":"string","enum":["api","email","webhook","risk","smtp","sms","sign","verify","forms","scheduling"],"description":"`api`: a request to the API. `email`: an email event. `webhook`: a delivery attempt. `risk`: a risk assessment or its feedback. `smtp`: a message submitted to the SMTP relay. `sms`: an SMS event."},"LogLevel":{"type":"string","enum":["info","warning","error"],"description":"`error`: 5xx responses, bounces, complaints, failures. `warning`: 4xx responses, delays, suppressions, failed webhook attempts that will be retried. `info`: everything else."},"AuditEventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"audit_event","id":"oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz","created_at":"2026-01-15T09:30:00.000Z","actor_type":"api_key","actor_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","actor_label":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","action":"suppression.created","target_type":"suppression","target_id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","target_label":"user@example.com","project_id":"proj_01k7c8m4q2f3e9v6t5r1n0p8yz","environment_id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz","metadata":{"scope":"*","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz"},"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0"}],"has_more":false}]},"AuditEvent":{"type":"object","properties":{"object":{"type":"string","enum":["audit_event"]},"id":{"type":"string","examples":["oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"created_at":{"type":"string","format":"date-time"},"actor_type":{"$ref":"#/components/schemas/AuditActorType"},"actor_id":{"type":["string","null"],"description":"The user's or API key's id; `null` for the system."},"actor_label":{"type":"string","description":"Who made the change, copied when it was recorded so it outlives them: the user's email, the API key's id, or `coss.com support`."},"action":{"type":"string","description":"`<resource>.<verb>`, e.g. `api_key.created`, `domain.deleted`, `member.role_changed`."},"target_type":{"type":["string","null"],"description":"What was changed: `domain`, `api_key`, `member`…"},"target_id":{"type":["string","null"],"description":"The id of what it acted on. `null`: nothing in particular."},"target_label":{"type":["string","null"],"description":"A readable name for the target when it was changed."},"project_id":{"type":["string","null"],"description":"`null` for organization-wide changes (domains, members…)."},"environment_id":{"type":["string","null"],"description":"`null` for organization-wide changes (domains, members…)."},"metadata":{"type":"object","additionalProperties":{},"description":"Details of the change; API changes include their `request_id`."},"client_ip":{"type":["string","null"],"description":"The actor's address. `null`: unknown."},"user_agent":{"type":["string","null"],"description":"The actor's `User-Agent`. `null`: unknown."}},"required":["object","id","created_at","actor_type","actor_id","actor_label","action","target_type","target_id","target_label","project_id","environment_id","metadata","client_ip","user_agent"],"examples":[{"object":"audit_event","id":"oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz","created_at":"2026-01-15T09:30:00.000Z","actor_type":"api_key","actor_id":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","actor_label":"key_01k7c8m4q2f3e9v6t5r1n0p8yz","action":"suppression.created","target_type":"suppression","target_id":"sup_01k7c8m4q2f3e9v6t5r1n0p8yz","target_label":"user@example.com","project_id":"proj_01k7c8m4q2f3e9v6t5r1n0p8yz","environment_id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz","metadata":{"scope":"*","request_id":"req_01k7c8m4q2f3e9v6t5r1n0p8yz"},"client_ip":"203.0.113.7","user_agent":"coss-node/0.1.0"}]},"AuditActorType":{"type":"string","enum":["user","api_key","system"],"description":"`user`: a member, in the dashboard (`actor_id` is the user's id, `actor_label` their email). `api_key`: a request made with an API key (`actor_id` is the key's id). `system`: coss.com itself, including coss.com support."},"Billing":{"type":"object","properties":{"object":{"type":"string","enum":["billing"]},"organization_id":{"type":"string","description":"The organization's id."},"plan":{"type":"string","enum":["free","pro","scale","enterprise"],"description":"The plan in effect now (`free` without a contract)."},"contract":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The contract's id."},"kind":{"type":"string","enum":["self_serve","sales","internal"],"description":"`self_serve`: chosen in the dashboard. `sales`: agreed with coss.com. `internal`: coss.com's own."},"effective_from":{"type":"string","format":"date-time","description":"When it took effect."},"effective_until":{"type":["string","null"],"format":"date-time","description":"When it ends. `null`: no end is set."},"term_end":{"type":["string","null"],"format":"date-time","description":"End of a committed term."},"auto_renew":{"type":"boolean","description":"Whether a committed term renews when it ends."}},"required":["id","kind","effective_from","effective_until","term_end","auto_renew"],"description":"The contract in effect; `null` on the Free plan."},"scheduled_change":{"type":["object","null"],"properties":{"effective_at":{"type":"string","format":"date-time","description":"When it takes effect."},"plan":{"type":"string","enum":["free","pro","scale","enterprise"],"description":"The plan it changes to."}},"required":["effective_at","plan"],"description":"A plan change that takes effect later (a downgrade, a cancellation)."},"status":{"type":"string","enum":["active","past_due","delinquent"],"description":"`past_due`: an invoice is overdue; `delinquent`: past its grace period, and live sending is held."},"holds":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["delinquent","spend_limit","credit_limit","admin"],"description":"`delinquent`: an invoice is past its grace period. `spend_limit`: the spend limit was reached. `credit_limit`: the credit limit was reached, or a usage charge failed. `admin`: placed by coss.com."},"since":{"type":"string","format":"date-time","description":"When the hold began."}},"required":["reason","since"]},"description":"Billing holds on live sending (sandbox keys keep working)."},"currency":{"type":"string","enum":["usd"],"description":"Always `usd`."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"When the period starts (inclusive)."},"end":{"type":"string","format":"date-time","description":"When the period ends (exclusive)."}},"required":["start","end"],"description":"The current billing month (UTC)."},"usage":{"type":"array","items":{"type":"object","properties":{"meter":{"type":"string","enum":["email.recipients","email.dedicated_ip","email.attachment_data","email.received","email.received_data","email.inboxes","sms.segments","sms.received_segments","sms.numbers","sms.registrations","sign.completed_requests","risk.phone_checks","risk.assessments","risk.content_checks","verify.verifications","verify.sms","forms.submissions","forms.file_uploads","scheduling.bookings","scheduling.hosts","hooks.messages"],"description":"What is counted, e.g. `email.recipients`."},"quantity":{"type":"integer","minimum":0,"description":"Units used so far this month."},"included":{"type":["integer","null"],"minimum":0,"description":"The plan's monthly allowance where usage stops (Free), else `null`."}},"required":["meter","quantity","included"]},"description":"This month's usage per meter."},"estimate":{"type":"object","properties":{"usage":{"type":"integer","description":"Usage this month at your rates."},"discount":{"type":"integer","description":"An amount in cents (USD)."},"credit":{"type":"integer","description":"Credit applied to this estimate (your plan's fee is credit)."},"total":{"type":"integer","description":"Estimated total including usage and fees billed in arrears, after discounts and credits."}},"required":["usage","discount","credit","total"],"description":"This month so far, as it would be invoiced if it ended now."},"credit_remaining":{"type":"integer","description":"Unused credit usable this month."},"spend_limit":{"type":["integer","null"],"description":"Usage beyond the credit past which live sending is held; `null`: none."},"credit_limit":{"type":["object","null"],"properties":{"limit":{"type":"integer","description":"What coss.com carries before live sending is held. It rises as payments settle."},"used":{"type":"integer","description":"Usage not invoiced yet, unpaid invoices and recent usage charges."},"charge_threshold":{"type":["integer","null"],"description":"Usage not invoiced yet is charged early at this amount; `null`: it isn't charged automatically."}},"required":["limit","used","charge_threshold"],"description":"Where the organization stands against its credit limit; `null`: it has none."},"payment_method":{"type":["object","null"],"properties":{"type":{"type":"string","description":"Its type, such as `card`."},"brand":{"type":["string","null"],"description":"The card's brand. `null` for other types."},"last4":{"type":["string","null"],"description":"The card's last four digits. `null` for other types."}},"required":["type","brand","last4"],"description":"The payment method on file. `null`: none."},"add_ons":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"e.g. `dedicated_ips`."},"name":{"type":"string","description":"The add-on's name."},"quantity":{"type":"integer","description":"How many units are on the contract."},"unit_amount":{"type":"integer","description":"The price per unit and interval, in cents."},"interval":{"type":"string","enum":["month","quarter","year"],"description":"How often it's charged."}},"required":["key","name","quantity","unit_amount","interval"]},"description":"Add-ons of the contract in effect, charged on top of the plan."},"features":{"type":"object","properties":{"tracking_domains":{"type":"boolean","description":"Custom tracking domains."},"audit_log":{"type":"boolean","description":"The organization's audit log."},"log_drains":{"type":"boolean","description":"Log drains."},"sso":{"type":"boolean","description":"Single sign-on."},"scim":{"type":"boolean","description":"Directory sync (SCIM)."},"dedicated_ips":{"type":"boolean","description":"Dedicated IP pools."}},"required":["tracking_domains","audit_log","log_drains","sso","scim","dedicated_ips"],"description":"Which features the plan includes."},"limits":{"type":"object","properties":{"domains":{"type":["integer","null"],"description":"Sending domains. `null`: unlimited."},"members":{"type":["integer","null"],"description":"Members of the organization. `null`: unlimited."},"webhook_endpoints_per_environment":{"type":["integer","null"],"description":"Webhook endpoints per environment. `null`: unlimited."},"contacts_per_environment":{"type":["integer","null"],"description":"Contacts per environment. `null`: unlimited."},"inboxes":{"type":["integer","null"],"description":"Inboxes. `null`: unlimited."}},"required":["domains","members","webhook_endpoints_per_environment","contacts_per_environment","inboxes"],"description":"Resource limits (`null`: unlimited)."}},"required":["object","organization_id","plan","contract","scheduled_change","status","holds","currency","period","usage","estimate","credit_remaining","spend_limit","credit_limit","payment_method","add_ons","features","limits"],"examples":[{"object":"billing","organization_id":"org_01k7c8m4q2f3e9v6t5r1n0p8yz","plan":"pro","contract":{"id":"bcon_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"self_serve","effective_from":"2026-10-01T00:00:00.000Z","effective_until":null,"term_end":null,"auto_renew":false},"scheduled_change":null,"status":"active","holds":[],"currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"usage":[{"meter":"email.recipients","quantity":120000,"included":null}],"estimate":{"usage":4800,"discount":0,"credit":2500,"total":2300},"credit_remaining":0,"spend_limit":null,"credit_limit":{"limit":50000,"used":2300,"charge_threshold":10000},"payment_method":{"type":"card","brand":"visa","last4":"4242"},"add_ons":[],"features":{"tracking_domains":true,"audit_log":true,"log_drains":false,"sso":false,"scim":false,"dedicated_ips":false},"limits":{"domains":10,"members":10,"webhook_endpoints_per_environment":10,"contacts_per_environment":50000,"inboxes":1000}}]},"UsageList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Usage"}},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"usage","meter":"email.recipients","dimension":null,"environment_id":null,"project_id":null,"api_key_id":null,"user_id":null,"start":"2026-10-12T00:00:00.000Z","end":"2026-10-13T00:00:00.000Z","quantity":4200}],"has_more":false}]},"Usage":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"meter":{"type":"string","enum":["email.recipients","email.dedicated_ip","email.attachment_data","email.received","email.received_data","email.inboxes","sms.segments","sms.received_segments","sms.numbers","sms.registrations","sign.completed_requests","risk.phone_checks","risk.assessments","risk.content_checks","verify.verifications","verify.sms","forms.submissions","forms.file_uploads","scheduling.bookings","scheduling.hosts","hooks.messages"],"description":"What is counted, e.g. `email.recipients`."},"dimension":{"type":["string","null"],"description":"e.g. `country=US` for SMS; `null` for none."},"environment_id":{"type":["string","null"],"description":"Set with `group_by=environment`; `null` there for organization-wide usage (SMS numbers and registration fees)."},"project_id":{"type":["string","null"],"description":"Set with `group_by=project` (`null`: organization-wide usage, or usage recorded before projects were)."},"api_key_id":{"type":["string","null"],"description":"Set with `group_by=api_key` (`null`: the dashboard, or usage recorded before keys were)."},"user_id":{"type":["string","null"],"description":"Set with `group_by=user`: the member whose personal API key caused it (`null`: organization keys and the dashboard)."},"start":{"type":"string","format":"date-time","description":"When this bucket starts (inclusive)."},"end":{"type":"string","format":"date-time","description":"When this bucket ends (exclusive)."},"quantity":{"type":"integer","minimum":0,"description":"Units used in this bucket."}},"required":["object","meter","dimension","environment_id","project_id","api_key_id","user_id","start","end","quantity"],"examples":[{"object":"usage","meter":"email.recipients","dimension":null,"environment_id":null,"project_id":null,"api_key_id":null,"user_id":null,"start":"2026-10-12T00:00:00.000Z","end":"2026-10-13T00:00:00.000Z","quantity":4200}]},"InvoiceList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceSummary"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"invoice","id":"inv_01k7c8m4q2f3e9v6t5r1n0p8yz","number":"COSS-000042","kind":"period","status":"paid","currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"subtotal":7300,"discount":0,"credit":2500,"tax":0,"total":4800,"amount_paid":4800,"amount_due":0,"collection_method":"charge_automatically","due_at":"2026-11-01T00:20:00.000Z","finalized_at":"2026-11-01T00:20:00.000Z","paid_at":"2026-11-01T00:21:00.000Z","voided_at":null,"hosted_url":"https://invoice.stripe.com/i/acct_123/test_YWNjdF8x","pdf_url":"https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf"}],"has_more":false}]},"Invoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string"},"number":{"type":["string","null"],"description":"The invoice number. `null` until it's finalized."},"kind":{"type":"string","enum":["period","plan_change","one_off","final","threshold"],"description":"`period`: a billing month. `plan_change`: a change of plan. `one_off`: a single charge. `final`: the last invoice of an account. `threshold`: usage charged early, taken off the month's invoice."},"status":{"type":"string","enum":["open","paid","void","uncollectible"],"description":"`open`: not paid yet. `paid`: settled. `void`: canceled. `uncollectible`: written off."},"currency":{"type":"string","enum":["usd"],"description":"Always `usd`."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"When the period starts (inclusive)."},"end":{"type":"string","format":"date-time","description":"When the period ends (exclusive)."}},"required":["start","end"],"description":"What period it covers."},"subtotal":{"type":"integer","description":"An amount in cents (USD)."},"discount":{"type":"integer","description":"An amount in cents (USD)."},"credit":{"type":"integer","description":"An amount in cents (USD)."},"tax":{"type":"integer","description":"An amount in cents (USD)."},"total":{"type":"integer","description":"An amount in cents (USD)."},"amount_paid":{"type":"integer","description":"An amount in cents (USD)."},"amount_due":{"type":"integer","description":"An amount in cents (USD)."},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"],"description":"`charge_automatically`: charged to the payment method. `send_invoice`: paid by `due_at`."},"due_at":{"type":["string","null"],"format":"date-time","description":"When payment is due. `null`: not set."},"finalized_at":{"type":["string","null"],"format":"date-time","description":"When it was finalized. `null`: not yet."},"paid_at":{"type":["string","null"],"format":"date-time","description":"When it was paid. `null`: not paid."},"voided_at":{"type":["string","null"],"format":"date-time","description":"When it was voided. `null`: it wasn't."},"hosted_url":{"type":["string","null"],"description":"A page to view (and pay) the invoice."},"pdf_url":{"type":["string","null"],"description":"The invoice as a PDF. `null`: not available."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"}}},"required":["object","id","number","kind","status","currency","period","subtotal","discount","credit","tax","total","amount_paid","amount_due","collection_method","due_at","finalized_at","paid_at","voided_at","hosted_url","pdf_url","lines"],"examples":[{"object":"invoice","id":"inv_01k7c8m4q2f3e9v6t5r1n0p8yz","number":"COSS-000042","kind":"period","status":"paid","currency":"usd","period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"},"subtotal":7300,"discount":0,"credit":2500,"tax":0,"total":4800,"amount_paid":4800,"amount_due":0,"collection_method":"charge_automatically","due_at":"2026-11-01T00:20:00.000Z","finalized_at":"2026-11-01T00:20:00.000Z","paid_at":"2026-11-01T00:21:00.000Z","voided_at":null,"hosted_url":"https://invoice.stripe.com/i/acct_123/test_YWNjdF8x","pdf_url":"https://pay.stripe.com/invoice/acct_123/test_YWNjdF8x/pdf","lines":[{"object":"invoice_line","id":"invl_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"usage","description":"Email: 120,000 recipients","meter":"email.recipients","dimension":null,"quantity":120000,"included_quantity":0,"unit_price":"0.0004","amount":4800,"period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"}}]}]},"InvoiceLine":{"type":"object","properties":{"object":{"type":"string","enum":["invoice_line"]},"id":{"type":"string"},"kind":{"type":"string","enum":["plan_fee","proration","usage","credit","discount","commitment_fee","commitment_shortfall","add_on","adjustment","write_off"],"description":"What it's for: `plan_fee`, `proration`, `usage`, `credit`, `discount`, `commitment_fee`, `commitment_shortfall`, `add_on`, `adjustment` or `write_off`."},"description":{"type":"string","description":"The line as it reads on the invoice."},"meter":{"type":["string","null"],"enum":["email.recipients","email.dedicated_ip","email.attachment_data","email.received","email.received_data","email.inboxes","sms.segments","sms.received_segments","sms.numbers","sms.registrations","sign.completed_requests","risk.phone_checks","risk.assessments","risk.content_checks","verify.verifications","verify.sms","forms.submissions","forms.file_uploads","scheduling.bookings","scheduling.hosts","hooks.messages",null],"description":"The meter of a `usage` line. `null` for other lines."},"dimension":{"type":["string","null"],"description":"What the meter is split by, such as `country=US`. `null`: not split."},"quantity":{"type":["integer","null"],"description":"Units on this line. `null` when it isn't priced by the unit."},"included_quantity":{"type":["integer","null"],"description":"Units covered by an allowance or committed volume (not charged)."},"unit_price":{"type":["string","null"],"description":"Dollars per unit, e.g. `0.0004`; `null` when the price varies by volume."},"amount":{"type":"integer","description":"An amount in cents (USD)."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"When the period starts (inclusive)."},"end":{"type":"string","format":"date-time","description":"When the period ends (exclusive)."}},"required":["start","end"],"description":"What period it covers."}},"required":["object","id","kind","description","meter","dimension","quantity","included_quantity","unit_price","amount","period"],"examples":[{"object":"invoice_line","id":"invl_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"usage","description":"Email: 120,000 recipients","meter":"email.recipients","dimension":null,"quantity":120000,"included_quantity":0,"unit_price":"0.0004","amount":4800,"period":{"start":"2026-10-01T00:00:00.000Z","end":"2026-11-01T00:00:00.000Z"}}]},"CreditList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Credit"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"credit","id":"bcg_01k7c8m4q2f3e9v6t5r1n0p8yz","kind":"units","amount":50000,"remaining":12000,"meter":"email.recipients","meters":null,"applies_to":"usage","source":"support","description":"Migration credit","effective_at":"2026-10-01T00:00:00.000Z","expires_at":"2027-01-01T00:00:00.000Z","voided_at":null,"created_at":"2026-10-01T09:30:00.000Z"}],"has_more":false}]},"LogDrainWithSecret":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain"]},"id":{"type":"string","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","description":"Where batches are posted.","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"],"description":"Your note about it. `null`: none."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"format":{"$ref":"#/components/schemas/LogDrainFormat"},"auth_header_name":{"type":["string","null"],"description":"The header sent with every batch to authenticate it (e.g. `Authorization`, `DD-API-KEY`), or `null`. Its value is never returned.","examples":["DD-API-KEY"]},"enabled":{"type":"boolean","description":"A disabled drain receives nothing, and lines logged while it is disabled are not kept for it."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: someone disabled it. `failing`: a batch failed every attempt, so coss.com disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When it was disabled. `null` while enabled."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"The drain's `whsec_…` signing secret, used to verify the batches coss.com sends. Returned only when the drain is created — store it now; it cannot be read back through the API.","examples":["whsec_6Jk…"]}},"required":["object","id","url","description","sources","format","auth_header_name","enabled","disabled_reason","disabled_at","created_at","updated_at","secret"],"examples":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"],"format":"ndjson","auth_header_name":null,"enabled":true,"disabled_reason":null,"disabled_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","secret":"whsec_6Jk…"}]},"LogDrainSource":{"type":"string","enum":["api","email","webhook","risk","smtp","sms","sign","verify","forms","scheduling","audit"],"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"LogDrainFormat":{"type":"string","enum":["ndjson","loki","datadog","otlp"],"description":"How batches are encoded. `ndjson`: one JSON object per line (`application/x-ndjson`), for your own endpoint. `loki`: Loki's push API (`/loki/api/v1/push`, Grafana Cloud Logs). `datadog`: Datadog's log intake (`/api/v2/logs`). `otlp`: OTLP/HTTP logs in JSON (`/v1/logs`, Grafana Cloud, Honeycomb, an OpenTelemetry Collector…)."},"CreateLogDrainRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL coss.com posts batches of log lines to.","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"maxItems":11,"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later. Defaults to every source."},"format":{"type":"string","enum":["ndjson","loki","datadog","otlp"],"description":"How batches are encoded. `ndjson`: one JSON object per line (`application/x-ndjson`), for your own endpoint. `loki`: Loki's push API (`/loki/api/v1/push`, Grafana Cloud Logs). `datadog`: Datadog's log intake (`/api/v2/logs`). `otlp`: OTLP/HTTP logs in JSON (`/v1/logs`, Grafana Cloud, Honeycomb, an OpenTelemetry Collector…). Defaults to `ndjson`."},"auth_header":{"$ref":"#/components/schemas/LogDrainAuthHeader"}},"required":["url"],"additionalProperties":false,"examples":[{"url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"]},{"url":"https://http-intake.logs.datadoghq.com/api/v2/logs","description":"Datadog","format":"datadog","auth_header":{"name":"DD-API-KEY","value":"<your Datadog API key>"}}]},"LogDrainAuthHeader":{"type":["object","null"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"The header's name.","examples":["Authorization"]},"value":{"type":"string","minLength":1,"maxLength":4096,"pattern":"^[\\t\\x20-\\x7e]+$","description":"The header's value. Encrypted, and never returned.","examples":["Bearer <token>"]}},"required":["name","value"],"additionalProperties":false,"description":"A header sent with every batch, for intake APIs that take a key: `Authorization` (`Basic …`, `Bearer …`), `DD-API-KEY`… Its value is stored encrypted and never returned. `null` removes it."},"LogDrainList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/LogDrain"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"],"format":"ndjson","auth_header_name":null,"enabled":true,"disabled_reason":null,"disabled_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"LogDrain":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain"]},"id":{"type":"string","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"url":{"type":"string","description":"Where batches are posted.","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"],"description":"Your note about it. `null`: none."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"format":{"$ref":"#/components/schemas/LogDrainFormat"},"auth_header_name":{"type":["string","null"],"description":"The header sent with every batch to authenticate it (e.g. `Authorization`, `DD-API-KEY`), or `null`. Its value is never returned.","examples":["DD-API-KEY"]},"enabled":{"type":"boolean","description":"A disabled drain receives nothing, and lines logged while it is disabled are not kept for it."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: someone disabled it. `failing`: a batch failed every attempt, so coss.com disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When it was disabled. `null` while enabled."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","url","description","sources","format","auth_header_name","enabled","disabled_reason","disabled_at","created_at","updated_at"],"examples":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://logs.example.com/coss","description":"Production logs","sources":["api","email"],"format":"ndjson","auth_header_name":null,"enabled":true,"disabled_reason":null,"disabled_at":null,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"UpdateLogDrainRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"An `https://` URL coss.com posts batches of log lines to.","examples":["https://logs.example.com/coss"]},"description":{"type":["string","null"],"maxLength":256,"description":"A note for your own reference. `null` clears it."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainSource"},"maxItems":11,"description":"What the drain forwards: `api` (requests made with the environment's API keys), `email` (email events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later."},"format":{"$ref":"#/components/schemas/LogDrainFormat"},"auth_header":{"$ref":"#/components/schemas/LogDrainAuthHeader"},"enabled":{"type":"boolean","description":"`false` disables it, and `true` enables it again."}},"additionalProperties":false,"examples":[{"enabled":false}]},"DeletedLogDrain":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"log_drain","id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"LogDrainBatchList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainBatch"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"log_drain_batch","id":"drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv","drain_id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"succeeded","line_count":42,"byte_size":31870,"attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"attempts":[{"object":"log_drain_attempt","id":"drainatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}],"has_more":false}]},"LogDrainBatch":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain_batch"]},"id":{"type":"string","description":"The batch's id: the `webhook-id` header, the same on every attempt.","examples":["drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"drain_id":{"type":"string","description":"The id of the drain it's posted to."},"status":{"$ref":"#/components/schemas/LogDrainBatchStatus"},"line_count":{"type":"integer","description":"Lines in the batch."},"byte_size":{"type":"integer","description":"Size of the request body in bytes."},"attempt_count":{"type":"integer","description":"How many attempts were made so far."},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"When the next attempt is due; `null` once the batch is finished."},"last_status_code":{"type":["integer","null"],"description":"The drain's HTTP status on the latest attempt. `null`: no response arrived, or no attempt yet."},"last_error":{"type":["string","null"],"description":"Why the latest attempt failed. `null`: it didn't, or no attempt yet."},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/LogDrainAttempt"},"description":"Every HTTP attempt of this batch, oldest first."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","drain_id","status","line_count","byte_size","attempt_count","next_attempt_at","last_status_code","last_error","attempts","created_at","updated_at"],"examples":[{"object":"log_drain_batch","id":"drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv","drain_id":"drain_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"succeeded","line_count":42,"byte_size":31870,"attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"attempts":[{"object":"log_drain_attempt","id":"drainatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:01.000Z"}]},"LogDrainBatchStatus":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending`: waiting for its next attempt. `succeeded`: the drain answered with a 2xx status. `failed`: every attempt failed, or the drain was disabled."},"LogDrainAttempt":{"type":"object","properties":{"object":{"type":"string","enum":["log_drain_attempt"]},"id":{"type":"string"},"attempted_at":{"type":"string","format":"date-time","description":"When the attempt ran."},"status_code":{"type":["integer","null"],"description":"The drain's HTTP status; `null` when no response arrived."},"duration_ms":{"type":"integer","description":"How long it took, in milliseconds."},"error":{"type":["string","null"],"description":"Why the attempt failed (e.g. `HTTP 500`, a timeout); `null` on success."},"response_excerpt":{"type":["string","null"],"description":"At most 1 KB of the response body, as text."}},"required":["object","id","attempted_at","status_code","duration_ms","error","response_excerpt"],"examples":[{"object":"log_drain_attempt","id":"drainatt_01k7c8n2c9e1g3j5l7n9q1s3uw","attempted_at":"2026-01-15T09:30:01.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}]},"HookEventType":{"type":"object","properties":{"object":{"type":"string","enum":["hook_event_type"]},"name":{"type":"string","description":"The type's name, which messages send as `event_type`.","examples":["invoice.paid"]},"description":{"type":["string","null"],"description":"What this event means, shown to your users. `null`: none."},"schema":{"type":["object","null"],"additionalProperties":{},"description":"A JSON Schema of the payload, shown to your users (not enforced). `null`: none."},"examples":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"Sample payloads, shown to your users. Test sends use the first."},"archived":{"type":"boolean","description":"Archived types are hidden from the portal and can't be subscribed to; messages of the type are still delivered to endpoints that subscribed before."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","name","description","schema","examples","archived","created_at","updated_at"],"examples":[{"object":"hook_event_type","name":"invoice.paid","description":"An invoice was paid in full.","schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"amount":{"type":"integer"}}},"examples":[{"invoice_id":"in_1042","amount":4200,"currency":"usd"}],"archived":false,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"CreateHookEventTypeRequest":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"The type's name, which messages send as `event_type`. Letters, digits and `. _ -`.","examples":["invoice.paid"]},"description":{"type":"string","maxLength":256,"description":"What this event means, shown to your users."},"schema":{"type":"object","additionalProperties":{},"description":"A JSON Schema of the payload, shown to your users (not enforced)."},"examples":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":5,"description":"Up to 5 example payloads; the first is what a test send delivers."}},"required":["name"],"additionalProperties":false,"examples":[{"name":"invoice.paid","description":"An invoice was paid in full.","examples":[{"invoice_id":"in_1042","amount":4200,"currency":"usd"}]}]},"HookEventTypeList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookEventType"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"hook_event_type","name":"invoice.paid","description":"An invoice was paid in full.","schema":{"type":"object","properties":{"invoice_id":{"type":"string"},"amount":{"type":"integer"}}},"examples":[{"invoice_id":"in_1042","amount":4200,"currency":"usd"}],"archived":false,"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"UpdateHookEventTypeRequest":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":256,"description":"What this event means, shown to your users. `null` removes it."},"schema":{"type":["object","null"],"additionalProperties":{},"description":"A JSON Schema of the payload, shown to your users (not enforced)."},"examples":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":5,"description":"Up to 5 example payloads; the first is what a test send delivers."},"archived":{"type":"boolean","description":"`false` restores an archived type."}},"additionalProperties":false,"examples":[{"archived":false}]},"HookApplication":{"type":"object","properties":{"object":{"type":"string","enum":["hook_application"]},"id":{"type":"string","examples":["happ_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"uid":{"type":["string","null"],"description":"Your own id for it (e.g. your customer's id), unique in the environment. Every path that takes an application accepts its `id` or its `uid`."},"name":{"type":"string","description":"Shown to the application's users in the portal."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","uid","name","metadata","created_at","updated_at"],"examples":[{"object":"hook_application","id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","uid":"customer_8812","name":"Acme Corp","metadata":{"plan":"pro"},"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"CreateHookApplicationRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Shown to the application's users in the portal.","examples":["Acme Corp"]},"uid":{"type":"string","pattern":"^[A-Za-z0-9_.:@|-]{1,256}$","description":"Your own id for it, to address it by in every path instead of its `id`.","examples":["customer_8812"]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs (at most 16; keys up to 40 characters, values up to 500).","examples":[{"plan":"pro"}]}},"required":["name"],"additionalProperties":false,"examples":[{"name":"Acme Corp","uid":"customer_8812","metadata":{"plan":"pro"}}]},"HookApplicationList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookApplication"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"hook_application","id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","uid":"customer_8812","name":"Acme Corp","metadata":{"plan":"pro"},"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"UpdateHookApplicationRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Shown to the application's users in the portal."},"uid":{"type":["string","null"],"pattern":"^[A-Za-z0-9_.:@|-]{1,256}$","description":"`null` removes it."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Replaces the metadata.","examples":[{"plan":"pro"}]}},"additionalProperties":false,"examples":[{"name":"Acme Corporation"}]},"DeletedHookApplication":{"type":"object","properties":{"object":{"type":"string","enum":["hook_application"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"hook_application","id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"HookEndpointWithSecret":{"type":"object","properties":{"object":{"type":"string","enum":["hook_endpoint"]},"id":{"type":"string","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"application_id":{"type":"string","description":"The id of the application it belongs to."},"url":{"type":"string","description":"Where deliveries are sent."},"description":{"type":["string","null"],"description":"Your note about it. `null`: none."},"filter_types":{"type":"array","items":{"type":"string"},"description":"Only these event types are delivered. Empty: every type."},"rate_limit_per_second":{"type":["integer","null"],"description":"At most this many requests per second to this endpoint. `null`: no limit of its own."},"enabled":{"type":"boolean","description":"Whether new messages are delivered to it."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: disabled by you or its user. `failing`: its deliveries failed every attempt for five days, so coss.com disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When it was disabled. `null`: it's enabled."},"failing_since":{"type":["string","null"],"format":"date-time","description":"When its current run of failed deliveries began; cleared by the next success. `null` while healthy."},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"After a secret roll, requests are also signed with the previous secret until then."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"The endpoint's `whsec_…` signing secret (Standard Webhooks).","examples":["whsec_6Jk…"]}},"required":["object","id","application_id","url","description","filter_types","rate_limit_per_second","enabled","disabled_reason","disabled_at","failing_since","previous_secret_expires_at","metadata","created_at","updated_at","secret"],"examples":[{"object":"hook_endpoint","id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks","description":"Production","filter_types":["invoice.paid"],"rate_limit_per_second":null,"enabled":true,"disabled_reason":null,"disabled_at":null,"failing_since":null,"previous_secret_expires_at":null,"metadata":{},"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","secret":"whsec_6Jk…"}]},"CreateHookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"examples":["https://example.com/webhooks"]},"description":{"type":"string","maxLength":256,"description":"Your note about it."},"filter_types":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"},"maxItems":250,"description":"Event types delivered to this endpoint (existing, unarchived ones). An empty array means every type, including ones added later.","examples":[["invoice.paid"]]},"secret":{"type":"string","description":"A `whsec_` + base64 secret of 24-64 bytes to sign with, e.g. when migrating from another provider. Generated when omitted."},"rate_limit_per_second":{"type":"integer","minimum":1,"maximum":1000,"description":"At most this many requests per second to this endpoint."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs (at most 16; keys up to 40 characters, values up to 500).","examples":[{"plan":"pro"}]},"enabled":{"type":"boolean","description":"Default `true`. `false` creates it disabled, with `disabled_reason: manual`."}},"required":["url"],"additionalProperties":false,"examples":[{"url":"https://example.com/webhooks","filter_types":["invoice.paid"]}]},"HookEndpointList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookEndpoint"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"hook_endpoint","id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks","description":"Production","filter_types":["invoice.paid"],"rate_limit_per_second":null,"enabled":true,"disabled_reason":null,"disabled_at":null,"failing_since":null,"previous_secret_expires_at":null,"metadata":{},"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"HookEndpoint":{"type":"object","properties":{"object":{"type":"string","enum":["hook_endpoint"]},"id":{"type":"string","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"application_id":{"type":"string","description":"The id of the application it belongs to."},"url":{"type":"string","description":"Where deliveries are sent."},"description":{"type":["string","null"],"description":"Your note about it. `null`: none."},"filter_types":{"type":"array","items":{"type":"string"},"description":"Only these event types are delivered. Empty: every type."},"rate_limit_per_second":{"type":["integer","null"],"description":"At most this many requests per second to this endpoint. `null`: no limit of its own."},"enabled":{"type":"boolean","description":"Whether new messages are delivered to it."},"disabled_reason":{"type":["string","null"],"enum":["manual","failing",null],"description":"`manual`: disabled by you or its user. `failing`: its deliveries failed every attempt for five days, so coss.com disabled it. `null` while enabled."},"disabled_at":{"type":["string","null"],"format":"date-time","description":"When it was disabled. `null`: it's enabled."},"failing_since":{"type":["string","null"],"format":"date-time","description":"When its current run of failed deliveries began; cleared by the next success. `null` while healthy."},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"After a secret roll, requests are also signed with the previous secret until then."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key-value pairs."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","application_id","url","description","filter_types","rate_limit_per_second","enabled","disabled_reason","disabled_at","failing_since","previous_secret_expires_at","metadata","created_at","updated_at"],"examples":[{"object":"hook_endpoint","id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://example.com/webhooks","description":"Production","filter_types":["invoice.paid"],"rate_limit_per_second":null,"enabled":true,"disabled_reason":null,"disabled_at":null,"failing_since":null,"previous_secret_expires_at":null,"metadata":{},"created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"UpdateHookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Where deliveries are sent."},"description":{"type":["string","null"],"maxLength":256,"description":"Your note about it. `null` removes it."},"filter_types":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$"},"maxItems":250,"description":"Event types delivered to this endpoint (existing, unarchived ones). An empty array means every type, including ones added later.","examples":[["invoice.paid"]]},"rate_limit_per_second":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"At most this many requests per second to this endpoint."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value pairs (at most 16; keys up to 40 characters, values up to 500).","examples":[{"plan":"pro"}]},"enabled":{"type":"boolean","description":"`false` disables it with `disabled_reason: manual`; `true` enables it again and clears the reason."}},"additionalProperties":false,"examples":[{"enabled":false}]},"DeletedHookEndpoint":{"type":"object","properties":{"object":{"type":"string","enum":["hook_endpoint"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"hook_endpoint","id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"HookEndpointSecret":{"type":"object","properties":{"object":{"type":"string","enum":["hook_endpoint_secret"]},"secret":{"type":"string","description":"The endpoint's `whsec_…` signing secret (Standard Webhooks)."}},"required":["object","secret"],"examples":[{"object":"hook_endpoint_secret","secret":"whsec_6Jk…"}]},"RollHookEndpointSecretRequest":{"type":"object","properties":{"previous_secret_expires_in":{"type":"integer","minimum":0,"maximum":604800,"description":"Seconds the current secret keeps signing next to the new one. Default 86400 (a day), at most 604800 (a week); `0` stops it immediately."}},"additionalProperties":false,"examples":[{"previous_secret_expires_in":3600}]},"HookEndpointRecovery":{"type":"object","properties":{"object":{"type":"string","enum":["hook_endpoint_recovery"]},"id":{"type":"string","examples":["hrec_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"endpoint_id":{"type":"string","description":"The id of the endpoint being recovered."},"since":{"type":"string","format":"date-time","description":"Deliveries of messages sent from this time on are requeued."},"until":{"type":"string","format":"date-time","description":"Up to this time: when the recovery was asked for."},"status":{"type":"string","enum":["pending","completed"],"description":"`pending` while coss.com is still requeueing deliveries (in the background)."},"requeued":{"type":"integer","description":"Deliveries requeued so far."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time","description":"When requeueing finished. `null`: still `pending`."}},"required":["object","id","endpoint_id","since","until","status","requeued","created_at","completed_at"],"examples":[{"object":"hook_endpoint_recovery","id":"hrec_01k7c8m4q2f3e9v6t5r1n0p8yz","endpoint_id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","since":"2026-01-15T00:00:00.000Z","until":"2026-01-15T09:30:00.000Z","status":"pending","requeued":0,"created_at":"2026-01-15T09:30:00.000Z","completed_at":null}]},"RecoverHookEndpointRequest":{"type":"object","properties":{"since":{"type":"string","format":"date-time","description":"Requeue deliveries that failed, of messages sent from this time until now.","examples":["2026-01-15T00:00:00.000Z"]}},"required":["since"],"additionalProperties":false,"examples":[{"since":"2026-01-15T00:00:00.000Z"}]},"HookMessage":{"type":"object","properties":{"object":{"type":"string","enum":["hook_message"]},"id":{"type":"string","description":"Also the `webhook-id` header of every request delivering it.","examples":["hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"application_id":{"type":"string","description":"The id of the application it was sent to."},"event_type":{"type":"string","description":"The event type it was sent as."},"payload":{"type":"object","additionalProperties":{},"description":"The JSON body delivered to each endpoint."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","application_id","event_type","payload","created_at"],"examples":[{"object":"hook_message","id":"hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","event_type":"invoice.paid","payload":{"invoice_id":"in_1042","amount":4200,"currency":"usd"},"created_at":"2026-01-15T09:30:00.000Z"}]},"SendHookTestRequest":{"type":"object","properties":{"event_type":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"The event type to send as.","examples":["invoice.paid"]},"payload":{"type":"object","additionalProperties":{},"description":"Defaults to the event type's first example."}},"required":["event_type"],"additionalProperties":false,"examples":[{"event_type":"invoice.paid"}]},"HookDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookDelivery"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"hook_delivery","id":"hdel_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","message_id":"hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz","endpoint_id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"succeeded","attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"created_at":"2026-01-15T09:30:00.000Z","finished_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"HookDelivery":{"type":"object","properties":{"object":{"type":"string","enum":["hook_delivery"]},"id":{"type":"string","examples":["hdel_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"application_id":{"type":"string","description":"The id of the application."},"message_id":{"type":"string","description":"The id of the message being delivered."},"endpoint_id":{"type":"string","description":"The id of the endpoint it's delivered to."},"status":{"type":"string","enum":["pending","succeeded","failed"],"description":"`pending`: waiting for its next attempt. `succeeded`: the endpoint answered 2xx. `failed`: every attempt failed, or the endpoint was disabled or deleted."},"attempt_count":{"type":"integer","description":"How many attempts were made so far."},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"When the next attempt runs. `null`: none is due, because it finished."},"last_status_code":{"type":["integer","null"],"description":"The endpoint's HTTP status on the latest attempt. `null`: no response arrived, or no attempt yet."},"last_error":{"type":["string","null"],"description":"Why the latest attempt failed. `null`: it didn't, or no attempt yet."},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time","description":"When it `succeeded` or `failed`. `null`: still `pending`."}},"required":["object","id","application_id","message_id","endpoint_id","status","attempt_count","next_attempt_at","last_status_code","last_error","created_at","finished_at"],"examples":[{"object":"hook_delivery","id":"hdel_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","message_id":"hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz","endpoint_id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"succeeded","attempt_count":1,"next_attempt_at":null,"last_status_code":200,"last_error":null,"created_at":"2026-01-15T09:30:00.000Z","finished_at":"2026-01-15T09:30:00.000Z"}]},"SendHookMessageRequest":{"type":"object","properties":{"event_type":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"What happened, e.g. `invoice.paid`. Endpoints that filter by type only get the types they chose. The type doesn't have to be registered.","examples":["invoice.paid"]},"payload":{"type":"object","additionalProperties":{},"description":"The JSON object delivered as the request body (at most 256 KB serialized). It is parsed and serialized again: send integers beyond 2^53 as strings.","examples":[{"invoice_id":"in_1042","amount":4200,"currency":"usd"}]}},"required":["event_type","payload"],"additionalProperties":false,"examples":[{"event_type":"invoice.paid","payload":{"invoice_id":"in_1042","amount":4200,"currency":"usd"}}]},"HookMessageList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookMessage"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"hook_message","id":"hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","event_type":"invoice.paid","payload":{"invoice_id":"in_1042","amount":4200,"currency":"usd"},"created_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"HookAttemptList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookAttempt"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"hook_attempt","id":"hatt_01k7c8m4q2f3e9v6t5r1n0p8yz","delivery_id":"hdel_01k7c8m4q2f3e9v6t5r1n0p8yz","endpoint_id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","attempted_at":"2026-01-15T09:30:00.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}],"has_more":false}]},"HookAttempt":{"type":"object","properties":{"object":{"type":"string","enum":["hook_attempt"]},"id":{"type":"string","examples":["hatt_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"delivery_id":{"type":"string","description":"The id of the delivery this attempt belongs to."},"endpoint_id":{"type":"string","description":"The id of the endpoint it was sent to."},"attempted_at":{"type":"string","format":"date-time","description":"When the attempt ran."},"status_code":{"type":["integer","null"],"description":"The endpoint's HTTP status; `null` when no response arrived."},"duration_ms":{"type":"integer","description":"How long it took, in milliseconds."},"error":{"type":["string","null"],"description":"Why it failed. `null`: it didn't."},"response_excerpt":{"type":["string","null"],"description":"At most 1 KB of the response body, as text."}},"required":["object","id","delivery_id","endpoint_id","attempted_at","status_code","duration_ms","error","response_excerpt"],"examples":[{"object":"hook_attempt","id":"hatt_01k7c8m4q2f3e9v6t5r1n0p8yz","delivery_id":"hdel_01k7c8m4q2f3e9v6t5r1n0p8yz","endpoint_id":"hep_01k7c8m4q2f3e9v6t5r1n0p8yz","attempted_at":"2026-01-15T09:30:00.000Z","status_code":200,"duration_ms":182,"error":null,"response_excerpt":"ok"}]},"HookPortalSession":{"type":"object","properties":{"object":{"type":"string","enum":["hook_portal_session"]},"id":{"type":"string","examples":["hps_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"application_id":{"type":"string","description":"The id of the application this session manages."},"url":{"type":"string","description":"Open it or embed it in an iframe (from an allowed origin). The token is in the URL fragment, so it never reaches a server log: hand the URL only to that application's user."},"token":{"type":"string","description":"The secret part of `url`, shown only here."},"read_only":{"type":"boolean","description":"Whether the user can only look."},"expires_at":{"type":"string","format":"date-time","description":"When the session stops working."}},"required":["object","id","application_id","url","token","read_only","expires_at"],"examples":[{"object":"hook_portal_session","id":"hps_01k7c8m4q2f3e9v6t5r1n0p8yz","application_id":"happ_01k7c8m4q2f3e9v6t5r1n0p8yz","url":"https://portal.example/s/hps_01k7c8m4q2f3e9v6t5r1n0p8yz#cossp_…","token":"cossp_…","read_only":false,"expires_at":"2026-01-15T10:30:00.000Z"}]},"CreateHookPortalSessionRequest":{"type":"object","properties":{"expires_in":{"type":"integer","minimum":60,"maximum":86400,"description":"Seconds until it expires: default 3600, at most 86400."},"read_only":{"type":"boolean","description":"The user can look but not change anything."}},"additionalProperties":false,"examples":[{"expires_in":3600}]},"ReceivedEmailList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedEmailSummary"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"received_email","id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"received","blocked_reason":null,"mail_from":"jane@example.com","recipients":["support@inbound.acme.com"],"from":"Jane Doe <jane@example.com>","to":["support@inbound.acme.com"],"cc":[],"subject":"Re: Your order","message_id":"<CAF3k2m9qp4ld8sv@mail.example.com>","attachments":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"invoice.pdf","content_type":"application/pdf","content_id":null,"disposition":"attachment","size":48213}],"size":61432,"spam":false,"verdicts":{"spam":"pass","virus":"pass","spf":"pass","dkim":"pass","dmarc":"pass","dmarc_policy":null},"sandbox":false,"received_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"ReceivedEmailSummary":{"type":"object","properties":{"object":{"type":"string","enum":["received_email"]},"id":{"type":"string","examples":["rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"status":{"type":"string","enum":["received","blocked"],"description":"`received`, or `blocked` when the message carried a virus: then only its envelope and verdicts are kept, never its content."},"blocked_reason":{"anyOf":[{"type":"string","enum":["virus"]},{"type":"null"}],"description":"Why it's `blocked`. `null`: it isn't."},"mail_from":{"type":"string","description":"The envelope sender (`MAIL FROM`); empty for bounces."},"recipients":{"type":"array","items":{"type":"string"},"description":"The envelope recipients this environment received the message for (Bcc'd addresses included, other organizations' never)."},"from":{"type":["string","null"],"description":"The `From` header."},"to":{"type":"array","items":{"type":"string"},"description":"The `To` header's addresses."},"cc":{"type":"array","items":{"type":"string"},"description":"The `Cc` header's addresses."},"subject":{"type":["string","null"],"description":"The `Subject` header. `null`: none."},"message_id":{"type":["string","null"],"description":"The `Message-ID` header."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedEmailAttachment"},"description":"Its attachments, without their bytes."},"size":{"type":"integer","description":"Size of the raw message in bytes."},"spam":{"type":"boolean","description":"Whether the spam verdict is `fail`."},"verdicts":{"$ref":"#/components/schemas/ReceivedEmailVerdicts"},"sandbox":{"type":"boolean","description":"Whether it was received by a sandbox environment."},"received_at":{"type":"string","format":"date-time","description":"When it arrived."}},"required":["object","id","status","blocked_reason","mail_from","recipients","from","to","cc","subject","message_id","attachments","size","spam","verdicts","sandbox","received_at"],"examples":[{"object":"received_email","id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"received","blocked_reason":null,"mail_from":"jane@example.com","recipients":["support@inbound.acme.com"],"from":"Jane Doe <jane@example.com>","to":["support@inbound.acme.com"],"cc":[],"subject":"Re: Your order","message_id":"<CAF3k2m9qp4ld8sv@mail.example.com>","attachments":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"invoice.pdf","content_type":"application/pdf","content_id":null,"disposition":"attachment","size":48213}],"size":61432,"spam":false,"verdicts":{"spam":"pass","virus":"pass","spf":"pass","dkim":"pass","dmarc":"pass","dmarc_policy":null},"sandbox":false,"received_at":"2026-10-10T12:00:00.000Z"}]},"ReceivedEmailAttachment":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":["string","null"],"description":"`null` when the part named none."},"content_type":{"type":"string"},"content_id":{"type":["string","null"],"description":"Set for parts the HTML references (`cid:` URLs)."},"disposition":{"type":"string","enum":["attachment","inline"]},"size":{"type":"integer","description":"Size in bytes."}},"required":["id","filename","content_type","content_id","disposition","size"],"examples":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"invoice.pdf","content_type":"application/pdf","content_id":null,"disposition":"attachment","size":48213}]},"InboundAddress":{"type":"object","properties":{"object":{"type":"string","enum":["inbound_address"]},"environment_id":{"type":"string"},"domain":{"type":"string","description":"Email sent to any address at this domain is received by the environment, with no DNS setup. It never changes."}},"required":["object","environment_id","domain"],"examples":[{"object":"inbound_address","environment_id":"env_01k7c8m4q2f3e9v6t5r1n0p8yz","domain":"k3j9x2m7qp4l.inbound.coss.com"}]},"ReceivedEmail":{"type":"object","properties":{"object":{"type":"string","enum":["received_email"]},"id":{"type":"string","examples":["rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"status":{"type":"string","enum":["received","blocked"],"description":"`received`, or `blocked` when the message carried a virus: then only its envelope and verdicts are kept, never its content."},"blocked_reason":{"anyOf":[{"type":"string","enum":["virus"]},{"type":"null"}],"description":"Why it's `blocked`. `null`: it isn't."},"mail_from":{"type":"string","description":"The envelope sender (`MAIL FROM`); empty for bounces."},"recipients":{"type":"array","items":{"type":"string"},"description":"The envelope recipients this environment received the message for (Bcc'd addresses included, other organizations' never)."},"from":{"type":["string","null"],"description":"The `From` header."},"to":{"type":"array","items":{"type":"string"},"description":"The `To` header's addresses."},"cc":{"type":"array","items":{"type":"string"},"description":"The `Cc` header's addresses."},"subject":{"type":["string","null"],"description":"The `Subject` header. `null`: none."},"message_id":{"type":["string","null"],"description":"The `Message-ID` header."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedEmailAttachment"},"description":"Its attachments, without their bytes."},"size":{"type":"integer","description":"Size of the raw message in bytes."},"spam":{"type":"boolean","description":"Whether the spam verdict is `fail`."},"verdicts":{"$ref":"#/components/schemas/ReceivedEmailVerdicts"},"sandbox":{"type":"boolean","description":"Whether it was received by a sandbox environment."},"received_at":{"type":"string","format":"date-time","description":"When it arrived."},"reply_to":{"type":"array","items":{"type":"string"},"description":"The `Reply-To` header's addresses."},"in_reply_to":{"type":["string","null"],"description":"The `In-Reply-To` header. `null`: none."},"references":{"type":"array","items":{"type":"string"},"description":"Message ids of the `References` header."},"sent_at":{"type":["string","null"],"format":"date-time","description":"The `Date` header, when valid."},"headers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The header's name."},"value":{"type":"string","description":"The header's value."}},"required":["name","value"]},"description":"Every header in message order (duplicates included)."},"text":{"type":["string","null"],"description":"The plain text body. `null`: none, or it's `blocked`."},"html":{"type":["string","null"],"description":"The HTML body. `null`: none, or it's `blocked`."},"truncated":{"type":"boolean","description":"Whether `text`, `html` or `headers` were shortened (2 MB per body, 64 KB of headers). The raw message always has all of it."}},"required":["object","id","status","blocked_reason","mail_from","recipients","from","to","cc","subject","message_id","attachments","size","spam","verdicts","sandbox","received_at","reply_to","in_reply_to","references","sent_at","headers","text","html","truncated"],"examples":[{"object":"received_email","id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","status":"received","blocked_reason":null,"mail_from":"jane@example.com","recipients":["support@inbound.acme.com"],"from":"Jane Doe <jane@example.com>","to":["support@inbound.acme.com"],"cc":[],"subject":"Re: Your order","message_id":"<CAF3k2m9qp4ld8sv@mail.example.com>","attachments":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"invoice.pdf","content_type":"application/pdf","content_id":null,"disposition":"attachment","size":48213}],"size":61432,"spam":false,"verdicts":{"spam":"pass","virus":"pass","spf":"pass","dkim":"pass","dmarc":"pass","dmarc_policy":null},"sandbox":false,"received_at":"2026-10-10T12:00:00.000Z","reply_to":[],"in_reply_to":"<x7f3k2m9qp4ld8sv@acme.com>","references":["<x7f3k2m9qp4ld8sv@acme.com>"],"sent_at":"2026-10-10T11:59:58.000Z","headers":[{"name":"From","value":"Jane Doe <jane@example.com>"},{"name":"To","value":"support@inbound.acme.com"},{"name":"Subject","value":"Re: Your order"}],"text":"Hi, the order arrived damaged.","html":"<p>Hi, the order arrived damaged.</p>","truncated":false}]},"DeletedReceivedEmail":{"type":"object","properties":{"object":{"type":"string","enum":["received_email"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"received_email","id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"Inbox":{"type":"object","properties":{"object":{"type":"string","enum":["inbox"]},"id":{"type":"string"},"address":{"type":"string","description":"The inbox's email address (`username@domain`)."},"username":{"type":"string","description":"The part of the address before the `@`."},"domain":{"type":"string","description":"The part of the address after the `@`."},"kind":{"type":"string","enum":["managed","domain"],"description":"`managed`: at the environment's own domain under coss.com's inbound domain (no DNS setup). `domain`: at one of the environment's receiving domains."},"display_name":{"type":["string","null"],"description":"The name messages from the inbox are sent with."},"client_id":{"type":["string","null"],"description":"Your own id for the inbox, e.g. your agent's or user's (unique per environment)."},"can_send":{"type":"boolean","description":"Whether messages can be sent from the inbox. Inboxes at coss.com's inbound domain only receive in live environments: create the inbox at a receiving domain under one of your verified domains to send from it."},"sandbox":{"type":"boolean","description":"Whether it belongs to a sandbox environment."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","address","username","domain","kind","display_name","client_id","can_send","sandbox","created_at","updated_at"],"examples":[{"object":"inbox","id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"support-agent@k3j9x2m7qp4l.inbound.coss.com","username":"support-agent","domain":"k3j9x2m7qp4l.inbound.coss.com","kind":"managed","display_name":"Acme Support","client_id":"agent-42","can_send":true,"sandbox":true,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}]},"CreateInboxRequest":{"type":"object","properties":{"username":{"type":"string","maxLength":64,"pattern":"^(?!.*\\.\\.)[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$","description":"The part before the @. Omit it for a random one. Mail to `username+anything@domain` reaches the inbox too.","examples":["support-agent"]},"domain":{"type":"string","minLength":1,"maxLength":253,"description":"One of the environment's receiving domains (its hostname). Omit it for the environment's own domain under coss.com's inbound domain, which needs no DNS setup.","examples":["agents.acme.com"]},"display_name":{"type":"string","minLength":1,"maxLength":64,"description":"The name messages from the inbox are sent with.","examples":["Acme Support"]},"client_id":{"type":"string","pattern":"^[\\x21-\\x7e]{1,128}$","description":"Your own id for the inbox (unique per environment). Creating an inbox with a `client_id` that already has one returns that inbox instead (200), so retries and \"one inbox per user\" need no bookkeeping.","examples":["agent-42"]}},"additionalProperties":false,"examples":[{"username":"support-agent","display_name":"Acme Support","client_id":"agent-42"}]},"InboxList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Inbox"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"inbox","id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","address":"support-agent@k3j9x2m7qp4l.inbound.coss.com","username":"support-agent","domain":"k3j9x2m7qp4l.inbound.coss.com","kind":"managed","display_name":"Acme Support","client_id":"agent-42","can_send":true,"sandbox":true,"created_at":"2026-10-10T12:00:00.000Z","updated_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"UpdateInboxRequest":{"type":"object","properties":{"display_name":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}],"description":"The name messages are sent with; `null` sends with the bare address."}},"additionalProperties":false,"examples":[{"display_name":"Acme Help"}]},"DeletedInbox":{"type":"object","properties":{"object":{"type":"string","enum":["inbox"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"inbox","id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","deleted":true}]},"InboxThreadList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxThreadSummary"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"inbox_thread","id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","subject":"My order arrived damaged","participants":["jane@example.com"],"message_count":2,"preview":"Sorry about that, Jane! A new one is on its way.","last_message_at":"2026-10-10T12:01:00.000Z","last_inbound_at":"2026-10-10T12:00:00.000Z","created_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"InboxThreadSummary":{"type":"object","properties":{"object":{"type":"string","enum":["inbox_thread"]},"id":{"type":"string"},"inbox_id":{"type":"string","description":"The inbox's id."},"subject":{"type":["string","null"],"description":"The first message's subject."},"participants":{"type":"array","items":{"type":"string"},"description":"Addresses of everyone in the conversation but the inbox (Bcc'd ones never)."},"message_count":{"type":"integer","description":"Messages in the thread."},"preview":{"type":["string","null"],"description":"The start of the latest message."},"last_message_at":{"type":"string","format":"date-time","description":"When its latest message was received or sent."},"last_inbound_at":{"type":["string","null"],"format":"date-time","description":"When its latest inbound message arrived: later than `last_message_at`'s outbound one means the conversation awaits a reply."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","inbox_id","subject","participants","message_count","preview","last_message_at","last_inbound_at","created_at"],"examples":[{"object":"inbox_thread","id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","subject":"My order arrived damaged","participants":["jane@example.com"],"message_count":2,"preview":"Sorry about that, Jane! A new one is on its way.","last_message_at":"2026-10-10T12:01:00.000Z","last_inbound_at":"2026-10-10T12:00:00.000Z","created_at":"2026-10-10T12:00:00.000Z"}]},"InboxThread":{"type":"object","properties":{"object":{"type":"string","enum":["inbox_thread"]},"id":{"type":"string"},"inbox_id":{"type":"string","description":"The inbox's id."},"subject":{"type":["string","null"],"description":"The first message's subject."},"participants":{"type":"array","items":{"type":"string"},"description":"Addresses of everyone in the conversation but the inbox (Bcc'd ones never)."},"message_count":{"type":"integer","description":"Messages in the thread."},"preview":{"type":["string","null"],"description":"The start of the latest message."},"last_message_at":{"type":"string","format":"date-time","description":"When its latest message was received or sent."},"last_inbound_at":{"type":["string","null"],"format":"date-time","description":"When its latest inbound message arrived: later than `last_message_at`'s outbound one means the conversation awaits a reply."},"created_at":{"type":"string","format":"date-time"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/InboxMessage"},"description":"The thread's messages, oldest first: its latest 50 (see `message_count`; list the inbox's messages for older ones)."}},"required":["object","id","inbox_id","subject","participants","message_count","preview","last_message_at","last_inbound_at","created_at","messages"],"examples":[{"object":"inbox_thread","id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","subject":"My order arrived damaged","participants":["jane@example.com"],"message_count":2,"preview":"Sorry about that, Jane! A new one is on its way.","last_message_at":"2026-10-10T12:01:00.000Z","last_inbound_at":"2026-10-10T12:00:00.000Z","created_at":"2026-10-10T12:00:00.000Z","messages":[{"object":"inbox_message","id":"imsg_01k7c8m4s1d3c9x0z4e6g7h8j9","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","thread_id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","direction":"inbound","status":"received","from":"Jane Doe <jane@example.com>","to":["support-agent@k3j9x2m7qp4l.inbound.coss.com"],"cc":[],"subject":"My order arrived damaged","preview":"Hi, the order arrived damaged. Can you send a new one?","attachments":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"photo.jpg","content_type":"image/jpeg","content_id":null,"disposition":"attachment","size":48213}],"spam":false,"received_email_id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":null,"created_at":"2026-10-10T12:00:00.000Z","reply_to":[],"message_id":"<CAF3k2m9qp4ld8sv@mail.example.com>","in_reply_to":null,"references":[],"text":"Hi, the order arrived damaged. Can you send a new one?\n\nJane","extracted_text":"Hi, the order arrived damaged. Can you send a new one?\n\nJane","html":null,"truncated":false},{"object":"inbox_message","id":"imsg_01k7c8m5t2e4d0y1a5f7h8j9k0","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","thread_id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","direction":"outbound","status":"queued","from":"\"Acme Support\" <support-agent@k3j9x2m7qp4l.inbound.coss.com>","to":["jane@example.com"],"cc":[],"subject":"Re: My order arrived damaged","preview":"Sorry about that, Jane! A new one is on its way.","attachments":[],"spam":false,"received_email_id":null,"email_id":"email_01k7c8m5t2e4d0y1a5f7h8j9k0","created_at":"2026-10-10T12:01:00.000Z","reply_to":[],"message_id":null,"in_reply_to":"<CAF3k2m9qp4ld8sv@mail.example.com>","references":["<CAF3k2m9qp4ld8sv@mail.example.com>"],"text":"Sorry about that, Jane! A new one is on its way.","extracted_text":"Sorry about that, Jane! A new one is on its way.","html":null,"truncated":false}]}]},"InboxMessage":{"type":"object","properties":{"object":{"type":"string","enum":["inbox_message"]},"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"`inbound`: received by the inbox. `outbound`: sent from it."},"status":{"type":"string","enum":["received","queued","sent","failed","scheduled","canceled"],"description":"`received` for inbound messages; an outbound message's email status (`queued`, `sent`, `failed`, …): its email has each recipient's delivery."},"from":{"type":["string","null"],"description":"The `From` header."},"to":{"type":"array","items":{"type":"string"},"description":"Addresses in the `To` header."},"cc":{"type":"array","items":{"type":"string"},"description":"Addresses in the `Cc` header."},"subject":{"type":["string","null"],"description":"The subject. `null`: none."},"preview":{"type":["string","null"],"description":"The start of the message's own text (without the quoted conversation)."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedEmailAttachment"},"description":"An inbound message's attachments (download them from the message)."},"spam":{"type":"boolean","description":"Whether the receiving server judged it spam."},"received_email_id":{"type":["string","null"],"description":"The received email of an inbound message."},"email_id":{"type":["string","null"],"description":"The email of an outbound message: its delivery events and webhooks name it."},"created_at":{"type":"string","format":"date-time","description":"When it was received or sent."},"reply_to":{"type":"array","items":{"type":"string"},"description":"Addresses in the `Reply-To` header."},"message_id":{"type":["string","null"],"description":"An inbound message's `Message-ID` header (outbound ones get theirs at sending)."},"in_reply_to":{"type":["string","null"],"description":"The message it answers, by `Message-ID`. `null`: none."},"references":{"type":"array","items":{"type":"string"},"description":"The `Message-ID`s of the conversation so far."},"text":{"type":["string","null"],"description":"The plain text part. `null`: none."},"extracted_text":{"type":["string","null"],"description":"The message's own text: `text` without the quoted conversation and signature below it (a heuristic; when nothing is left, all of `text`). Made from `html` when there is no `text`."},"html":{"type":["string","null"],"description":"The sender's HTML: sanitize it before showing it to anyone."},"truncated":{"type":"boolean","description":"Whether `text` or `html` were shortened (2 MB each)."}},"required":["object","id","inbox_id","thread_id","direction","status","from","to","cc","subject","preview","attachments","spam","received_email_id","email_id","created_at","reply_to","message_id","in_reply_to","references","text","extracted_text","html","truncated"],"examples":[{"object":"inbox_message","id":"imsg_01k7c8m4s1d3c9x0z4e6g7h8j9","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","thread_id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","direction":"inbound","status":"received","from":"Jane Doe <jane@example.com>","to":["support-agent@k3j9x2m7qp4l.inbound.coss.com"],"cc":[],"subject":"My order arrived damaged","preview":"Hi, the order arrived damaged. Can you send a new one?","attachments":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"photo.jpg","content_type":"image/jpeg","content_id":null,"disposition":"attachment","size":48213}],"spam":false,"received_email_id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":null,"created_at":"2026-10-10T12:00:00.000Z","reply_to":[],"message_id":"<CAF3k2m9qp4ld8sv@mail.example.com>","in_reply_to":null,"references":[],"text":"Hi, the order arrived damaged. Can you send a new one?\n\nJane","extracted_text":"Hi, the order arrived damaged. Can you send a new one?\n\nJane","html":null,"truncated":false},{"object":"inbox_message","id":"imsg_01k7c8m5t2e4d0y1a5f7h8j9k0","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","thread_id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","direction":"outbound","status":"queued","from":"\"Acme Support\" <support-agent@k3j9x2m7qp4l.inbound.coss.com>","to":["jane@example.com"],"cc":[],"subject":"Re: My order arrived damaged","preview":"Sorry about that, Jane! A new one is on its way.","attachments":[],"spam":false,"received_email_id":null,"email_id":"email_01k7c8m5t2e4d0y1a5f7h8j9k0","created_at":"2026-10-10T12:01:00.000Z","reply_to":[],"message_id":null,"in_reply_to":"<CAF3k2m9qp4ld8sv@mail.example.com>","references":["<CAF3k2m9qp4ld8sv@mail.example.com>"],"text":"Sorry about that, Jane! A new one is on its way.","extracted_text":"Sorry about that, Jane! A new one is on its way.","html":null,"truncated":false}]},"DeletedInboxThread":{"type":"object","properties":{"object":{"type":"string","enum":["inbox_thread"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"inbox_thread","id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","deleted":true}]},"InboxMessageList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/InboxMessageSummary"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"inbox_message","id":"imsg_01k7c8m4s1d3c9x0z4e6g7h8j9","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","thread_id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","direction":"inbound","status":"received","from":"Jane Doe <jane@example.com>","to":["support-agent@k3j9x2m7qp4l.inbound.coss.com"],"cc":[],"subject":"My order arrived damaged","preview":"Hi, the order arrived damaged. Can you send a new one?","attachments":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"photo.jpg","content_type":"image/jpeg","content_id":null,"disposition":"attachment","size":48213}],"spam":false,"received_email_id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":null,"created_at":"2026-10-10T12:00:00.000Z"}],"has_more":false}]},"InboxMessageSummary":{"type":"object","properties":{"object":{"type":"string","enum":["inbox_message"]},"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"`inbound`: received by the inbox. `outbound`: sent from it."},"status":{"type":"string","enum":["received","queued","sent","failed","scheduled","canceled"],"description":"`received` for inbound messages; an outbound message's email status (`queued`, `sent`, `failed`, …): its email has each recipient's delivery."},"from":{"type":["string","null"],"description":"The `From` header."},"to":{"type":"array","items":{"type":"string"},"description":"Addresses in the `To` header."},"cc":{"type":"array","items":{"type":"string"},"description":"Addresses in the `Cc` header."},"subject":{"type":["string","null"],"description":"The subject. `null`: none."},"preview":{"type":["string","null"],"description":"The start of the message's own text (without the quoted conversation)."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedEmailAttachment"},"description":"An inbound message's attachments (download them from the message)."},"spam":{"type":"boolean","description":"Whether the receiving server judged it spam."},"received_email_id":{"type":["string","null"],"description":"The received email of an inbound message."},"email_id":{"type":["string","null"],"description":"The email of an outbound message: its delivery events and webhooks name it."},"created_at":{"type":"string","format":"date-time","description":"When it was received or sent."}},"required":["object","id","inbox_id","thread_id","direction","status","from","to","cc","subject","preview","attachments","spam","received_email_id","email_id","created_at"],"examples":[{"object":"inbox_message","id":"imsg_01k7c8m4s1d3c9x0z4e6g7h8j9","inbox_id":"inbox_01k7c8m4q2f3e9v6t5r1n0p8yz","thread_id":"thread_01k7c8m4r0c2b8w9y3d5f6g7h8","direction":"inbound","status":"received","from":"Jane Doe <jane@example.com>","to":["support-agent@k3j9x2m7qp4l.inbound.coss.com"],"cc":[],"subject":"My order arrived damaged","preview":"Hi, the order arrived damaged. Can you send a new one?","attachments":[{"id":"rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8","filename":"photo.jpg","content_type":"image/jpeg","content_id":null,"disposition":"attachment","size":48213}],"spam":false,"received_email_id":"rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz","email_id":null,"created_at":"2026-10-10T12:00:00.000Z"}]},"SendInboxMessageRequest":{"type":"object","properties":{"to":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":1,"maxItems":50}],"description":"Who it goes to."},"cc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}],"description":"Who it's copied to."},"bcc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}],"description":"Who it's blind copied to."},"subject":{"type":"string","minLength":1,"maxLength":998,"description":"The new thread's subject."},"text":{"type":"string","description":"Plain-text body. Without it, an `html` email goes out with a text part generated from the HTML."},"html":{"type":"string","description":"HTML body. Provide `html`, `text`, or both."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SendEmailAttachment"},"maxItems":20,"description":"Up to 20 files, at most 25 MB combined."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's name, unique on the email."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's value."}},"required":["name","value"],"additionalProperties":false},"maxItems":50,"description":"Your tags on the email."}},"required":["to","subject"],"additionalProperties":false,"description":"Starts a thread: the message is sent from the inbox's address.","examples":[{"to":"jane@example.com","subject":"Your order","text":"Hi Jane, your order has shipped."}]},"ReplyInboxMessageRequest":{"type":"object","properties":{"reply_all":{"type":"boolean","description":"Also reply to everyone else on the message (its `to` and `cc`, but the inbox). Default `false`: only the sender (its `Reply-To`, when it has one)."},"cc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}],"description":"Who it's copied to."},"bcc":{"anyOf":[{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},{"type":"array","items":{"type":"string","description":"An email address, optionally with a display name: \"Acme <hello@acme.com>\"."},"minItems":0,"maxItems":50}],"description":"Who it's blind copied to."},"text":{"type":"string","description":"Plain-text body. Without it, an `html` email goes out with a text part generated from the HTML."},"html":{"type":"string","description":"HTML body. Provide `html`, `text`, or both."},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SendEmailAttachment"},"maxItems":20,"description":"Up to 20 files, at most 25 MB combined."},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's name, unique on the email."},"value":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The tag's value."}},"required":["name","value"],"additionalProperties":false},"maxItems":50,"description":"Your tags on the email."}},"additionalProperties":false,"description":"Replies in the message's thread, from the inbox's address, with `Re:` and the headers mail clients thread by (`In-Reply-To`, `References`).","examples":[{"text":"Sorry about that, Jane! A new one is on its way."}]},"RiskAssessment":{"type":"object","properties":{"object":{"type":"string","enum":["risk_assessment"]},"id":{"type":"string","examples":["rsk_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"event":{"$ref":"#/components/schemas/RiskEvent"},"event_name":{"type":["string","null"],"description":"Your name for a `custom` event. `null`: none."},"decision":{"$ref":"#/components/schemas/RiskDecision"},"score":{"type":"number","minimum":0,"maximum":1,"description":"0-1: how risky the signals are together. Lists can decide regardless of the score."},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/RiskReason"},"description":"Why, most significant first."},"signals":{"type":"object","properties":{"email":{"anyOf":[{"$ref":"#/components/schemas/RiskEmailSignals"},{"type":"null"}],"description":"What the address says. `null`: no email was given."},"ip":{"anyOf":[{"$ref":"#/components/schemas/RiskIpSignals"},{"type":"null"}],"description":"What the IP address says. `null`: none was given."},"velocity":{"anyOf":[{"$ref":"#/components/schemas/RiskVelocitySignals"},{"type":"null"}],"description":"`null` when velocity was unavailable (see `degraded`)."},"captcha":{"anyOf":[{"$ref":"#/components/schemas/RiskCaptchaSignals"},{"type":"null"}],"description":"How the captcha went. `null`: no captcha applied."},"login":{"anyOf":[{"$ref":"#/components/schemas/RiskLoginSignals"},{"type":"null"}],"description":"Whether a login is new for this user. `null`: not a login of a user with history."},"content":{"anyOf":[{"$ref":"#/components/schemas/RiskContentSignals"},{"type":"null"}],"description":"`null` when no content was given or it couldn't be classified."},"checkout":{"anyOf":[{"$ref":"#/components/schemas/RiskCheckoutSignals"},{"type":"null"}],"description":"What you sent in `checkout`. `null`: not given."},"device":{"anyOf":[{"$ref":"#/components/schemas/RiskDeviceSignals"},{"type":"null"}],"description":"What the device token said. `null`: none was given."}},"required":["email","ip","velocity","captcha","login","content","checkout","device"],"description":"What the assessment saw, by group. A group is `null` when it had nothing to go on."},"user":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Your user id. `null`: none given."},"email":{"type":["string","null"],"description":"`null` once removed (90 days after the assessment) or when none was given."}},"required":["id","email"],"description":"Who it's about."},"ip":{"type":["string","null"],"description":"`null` once removed (90 days after)."},"degraded":{"type":"array","items":{"type":"string","enum":["email_dns","domain_age","ip_data","velocity","captcha","content","ip_privacy","usage_limit"]},"description":"Signal groups that were unavailable for this assessment (it was made without them). `usage_limit` means the plan's included assessments are used up, or a billing hold or budget applies: the assessment was free and made without velocity, memory of earlier events, content or address-level IP data."},"outcome":{"anyOf":[{"$ref":"#/components/schemas/RiskOutcome"},{"type":"null"}],"description":"The latest outcome you reported with feedback."},"review_status":{"anyOf":[{"type":"string","enum":["open","resolved"]},{"type":"null"}],"description":"`open` for `review` decisions until you send feedback, then `resolved`."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","event","event_name","decision","score","reasons","signals","user","ip","degraded","outcome","review_status","created_at"],"examples":[{"object":"risk_assessment","id":"rsk_01k7c8m4q2f3e9v6t5r1n0p8yz","event":"signup","event_name":null,"decision":"review","score":0.62,"reasons":[{"code":"email.typo","message":"The domain looks like a typo of gmail.com.","suggestion":"gmail.com"},{"code":"velocity.signups_per_ip_1h","message":"7 sign-ups from this IP address in the last hour.","value":7,"threshold":5,"window":"1h"}],"signals":{"email":{"domain":"gmail.con","valid":true,"disposable":false,"deliverability":"deliverable","role_account":false,"free_provider":false,"suggestion":"gmail.com","domain_age_days":9},"ip":{"version":4,"private":false,"tor":false,"hosting":false,"hosting_provider":null,"hosting_kind":null,"asn":64500,"as_name":"Example Broadband","country":"GB","privacy":null},"velocity":{"ip_1h":7,"ip_24h":9,"subnet_1h":7,"mailbox_24h":1},"captcha":{"provided":true,"passed":true},"login":null,"content":null,"checkout":null,"device":null},"user":{"id":null,"email":"ada@gmail.con"},"ip":"203.0.113.7","degraded":[],"outcome":null,"review_status":"open","created_at":"2026-01-15T09:30:00.000Z"}]},"RiskEmailSignals":{"type":"object","properties":{"domain":{"type":["string","null"],"description":"`null` once the address is removed (90 days after the assessment)."},"valid":{"type":"boolean","description":"Whether it's syntactically valid."},"disposable":{"type":"boolean","description":"Whether its domain is a known burner service."},"deliverability":{"type":"string","enum":["deliverable","undeliverable","unknown"],"description":"From DNS (MX, A, AAAA). `unknown` when the lookup failed or timed out."},"role_account":{"type":"boolean","description":"Whether it's a role mailbox, like `info@`."},"free_provider":{"type":"boolean","description":"Whether its domain is a free mailbox provider."},"suggestion":{"type":["string","null"],"description":"`email.typo`: the likely intended domain. `null` otherwise."},"domain_age_days":{"type":["integer","null"],"description":"Days since the domain was registered (RDAP); `null` when unknown or not looked up (free providers, disposable domains)."}},"required":["domain","valid","disposable","deliverability","role_account","free_provider","suggestion","domain_age_days"],"description":"What the address says. `null` on an assessment with no email."},"RiskIpSignals":{"type":"object","properties":{"version":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]}],"description":"IPv4 or IPv6."},"private":{"type":"boolean","description":"Whether it's a private or reserved address."},"tor":{"type":"boolean","description":"Whether it's a Tor exit."},"hosting":{"type":"boolean","description":"Whether it's in a cloud, hosting or VPN network."},"hosting_provider":{"type":["string","null"],"description":"That network's operator. `null` when it isn't one."},"hosting_kind":{"type":["string","null"],"enum":["cloud","hosting","vpn",null],"description":"`cloud`, `hosting` or `vpn`. `null` when it isn't one."},"asn":{"type":["integer","null"],"description":"The network's autonomous system number. `null` when unknown."},"as_name":{"type":["string","null"],"description":"The network's name. `null` when unknown."},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2."},"privacy":{"anyOf":[{"$ref":"#/components/schemas/RiskIpPrivacy"},{"type":"null"}],"description":"From coss.com's IP privacy data provider (VPNs, proxies, relays). `null` when it isn't available or was not asked (private addresses)."}},"required":["version","private","tor","hosting","hosting_provider","hosting_kind","asn","as_name","country","privacy"],"description":"What the address says. `null` on an assessment with no IP."},"RiskIpPrivacy":{"type":"object","properties":{"vpn":{"type":"boolean","description":"Whether it's a VPN exit."},"proxy":{"type":"boolean","description":"Whether it's a proxy."},"relay":{"type":"boolean","description":"Whether it's a privacy relay."},"service":{"type":["string","null"],"description":"The VPN or proxy service."}},"required":["vpn","proxy","relay","service"]},"RiskVelocitySignals":{"type":"object","additionalProperties":{"type":"integer"},"description":"Events of the same kind in this environment, this one included, keyed `<dimension>_<window>` (e.g. `ip_1h`, `mailbox_24h`)."},"RiskCaptchaSignals":{"type":"object","properties":{"provided":{"type":"boolean","description":"Whether the request carried a token."},"passed":{"type":["boolean","null"],"description":"`null` when it couldn't be checked (no captcha configured, or the provider was unreachable)."}},"required":["provided","passed"],"description":"How the captcha went. `null` when no captcha applies."},"RiskLoginSignals":{"type":"object","properties":{"new_country":{"type":"boolean","description":"Whether this user never logged in from this country in this environment."},"new_network":{"type":"boolean","description":"Whether this user never logged in from this network (ASN) in this environment."}},"required":["new_country","new_network"],"description":"Logins of a user with history: whether the country or network is new for them."},"RiskContentSignals":{"type":"object","properties":{"spam":{"type":"number","minimum":0,"maximum":1,"description":"The model's probability (0-1) that it's spam."},"phishing":{"type":"number","minimum":0,"maximum":1,"description":"The model's probability (0-1) that it's phishing."},"malware":{"type":"number","minimum":0,"maximum":1,"description":"The model's probability (0-1) that it's malware."},"fraud":{"type":"number","minimum":0,"maximum":1,"description":"The model's probability (0-1) that it's fraud."}},"required":["spam","phishing","malware","fraud"],"description":"Per category, the model's probability (0-1) that the content belongs to it. Scores are not calibrated: pick thresholds by looking at your own traffic."},"RiskCheckoutSignals":{"type":"object","properties":{"amount":{"type":"integer","description":"The amount you sent, in the currency's smallest unit."},"currency":{"type":"string","description":"The currency you sent."},"card_country":{"type":["string","null"],"description":"The card's country. `null` when not given."},"card_funding":{"type":["string","null"],"enum":["credit","debit","prepaid","unknown",null],"description":"The card's funding type. `null` when not given."},"billing_country":{"type":["string","null"],"description":"The billing country. `null` when not given."},"shipping_country":{"type":["string","null"],"description":"The shipping country. `null` when not given."}},"required":["amount","currency","card_country","card_funding","billing_country","shipping_country"],"description":"What you sent in `checkout` (never the card)."},"RiskDeviceSignals":{"type":"object","properties":{"valid":{"type":"boolean","description":"`false`: the token was malformed or too old."},"automation":{"type":"boolean","description":"WebDriver control or a headless browser."},"timezone":{"type":["string","null"],"description":"IANA time zone (`Europe/London`)."},"language":{"type":["string","null"],"description":"The browser's first language."},"platform":{"type":["string","null"],"description":"The browser's reported platform. `null` when it reported none."},"screen":{"type":["string","null"],"description":"`<width>x<height>` in CSS pixels."},"touch":{"type":["boolean","null"],"description":"Whether the device has a touch screen. `null` when it didn't say."}},"required":["valid","automation","timezone","language","platform","screen","touch"],"description":"What the browser reported through `coss/device` (its device id is only kept as a keyed hash)."},"CreateRiskAssessmentRequest":{"type":"object","properties":{"event":{"$ref":"#/components/schemas/RiskEvent"},"event_name":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$","description":"Required for `custom` events (e.g. `invite_sent`), not allowed otherwise."},"user":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"description":"Your id for the user, when it exists (logins always; sign-ups once the account is created)."},"email":{"type":"string","minLength":1,"maxLength":320,"description":"The email address the user gave. Checked as given, even if invalid."}},"additionalProperties":false},"ip":{"anyOf":[{"type":"string","format":"ip"},{"type":"string","format":"ip"}],"description":"The client's IP address (not your server's or proxy's)."},"user_agent":{"type":"string","maxLength":1024,"description":"The client's user agent."},"captcha":{"type":"object","properties":{"token":{"type":"string","minLength":1,"maxLength":4096,"description":"The token your captcha widget (Turnstile or hCaptcha, set in the environment's risk settings) gave the browser. Verified once: don't reuse it."}},"required":["token"],"additionalProperties":false},"checkout":{"$ref":"#/components/schemas/RiskCheckoutRequest"},"device":{"type":"object","properties":{"token":{"type":"string","minLength":1,"maxLength":4096,"description":"What `collectDevice()` from `coss/device` returned in the user's browser, passed through your server."}},"required":["token"],"additionalProperties":false,"description":"The browser the event came from: recognizes it across accounts (`duplicate.device`, device velocity, fraud memory) and spots automation."},"content":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":50000,"description":"Text the user wrote (a profile bio, a message, a listing). Classified by an AI model with zero data retention and never stored: only its scores are."}},"required":["text"],"additionalProperties":false,"description":"Content to classify with the event. Its scores go in `signals.content` and rules can test them; `content.*` reasons fire only at thresholds you set."}},"required":["event"],"additionalProperties":false,"examples":[{"event":"signup","user":{"email":"ada@gmail.con"},"ip":"203.0.113.7","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 15_0) AppleWebKit/605.1.15"}]},"RiskCheckoutRequest":{"type":"object","properties":{"amount":{"type":"integer","minimum":0,"maximum":1000000000000,"description":"The amount in the currency's minor unit (cents for USD: 1999 is $19.99)."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217, upper-case (`USD`)."},"card":{"type":"object","properties":{"fingerprint":{"type":"string","minLength":1,"maxLength":256,"description":"Your payment processor's fingerprint of the card number (Stripe: `card.fingerprint`). Counted and remembered as a keyed hash only; never send the card number."},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Where the card was issued."},"funding":{"type":"string","enum":["credit","debit","prepaid","unknown"]}},"additionalProperties":false,"description":"What your payment processor tells you about the card."},"billing_country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2, upper-case (`GB`)."},"shipping_country":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2, upper-case (`GB`)."}},"required":["amount","currency"],"additionalProperties":false,"description":"Only with `checkout` events: what is being paid for, and with which card."},"RiskAssessmentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RiskAssessment"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"risk_assessment","id":"rsk_01k7c8m4q2f3e9v6t5r1n0p8yz","event":"signup","event_name":null,"decision":"review","score":0.62,"reasons":[{"code":"email.typo","message":"The domain looks like a typo of gmail.com.","suggestion":"gmail.com"},{"code":"velocity.signups_per_ip_1h","message":"7 sign-ups from this IP address in the last hour.","value":7,"threshold":5,"window":"1h"}],"signals":{"email":{"domain":"gmail.con","valid":true,"disposable":false,"deliverability":"deliverable","role_account":false,"free_provider":false,"suggestion":"gmail.com","domain_age_days":9},"ip":{"version":4,"private":false,"tor":false,"hosting":false,"hosting_provider":null,"hosting_kind":null,"asn":64500,"as_name":"Example Broadband","country":"GB","privacy":null},"velocity":{"ip_1h":7,"ip_24h":9,"subnet_1h":7,"mailbox_24h":1},"captcha":{"provided":true,"passed":true},"login":null,"content":null,"checkout":null,"device":null},"user":{"id":null,"email":"ada@gmail.con"},"ip":"203.0.113.7","degraded":[],"outcome":null,"review_status":"open","created_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"CreateRiskFeedbackRequest":{"type":"object","properties":{"outcome":{"$ref":"#/components/schemas/RiskOutcome"},"note":{"type":"string","maxLength":500,"description":"For your team; never shared."}},"required":["outcome"],"additionalProperties":false,"examples":[{"outcome":"fraud"}]},"RiskListEntry":{"type":"object","properties":{"object":{"type":"string","enum":["risk_list_entry"]},"id":{"type":"string"},"list":{"$ref":"#/components/schemas/RiskList"},"type":{"$ref":"#/components/schemas/RiskListEntryType"},"value":{"type":"string","description":"Normalized: emails as their mailbox, CIDR ranges canonical, ASNs as numbers."},"note":{"type":["string","null"],"description":"Your note about it. `null`: none."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When it stops matching. `null`: never."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","list","type","value","note","expires_at","created_at"],"examples":[{"object":"risk_list_entry","id":"rskle_01k7c8m4q2f3e9v6t5r1n0p8yz","list":"block","type":"domain","value":"evil.example","note":"Card testing","expires_at":null,"created_at":"2026-01-15T09:30:00.000Z"}]},"RiskList":{"type":"string","enum":["allow","block"],"description":"Which list: `allow` or `block`."},"RiskListEntryType":{"type":"string","enum":["email","domain","ip","asn","country","user"],"description":"`email` (matched by mailbox, dots and `+tags` folded), `domain` (subdomains included), `ip` (an address or CIDR range), `asn`, `country` (ISO 3166-1 alpha-2), `user` (your user id)."},"CreateRiskListEntryRequest":{"type":"object","properties":{"list":{"$ref":"#/components/schemas/RiskList"},"type":{"$ref":"#/components/schemas/RiskListEntryType"},"value":{"type":"string","minLength":1,"maxLength":320,"description":"What to match: the address, domain, IP, CIDR range, ASN or other value of its `type`."},"note":{"type":"string","maxLength":500,"description":"Your note about it."},"expires_at":{"type":"string","format":"date-time","description":"The entry stops matching at this time (it is kept until deleted)."}},"required":["list","type","value"],"additionalProperties":false,"examples":[{"list":"block","type":"domain","value":"evil.example","note":"Card testing"}]},"RiskListEntryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RiskListEntry"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"examples":[{"object":"list","data":[{"object":"risk_list_entry","id":"rskle_01k7c8m4q2f3e9v6t5r1n0p8yz","list":"block","type":"domain","value":"evil.example","note":"Card testing","expires_at":null,"created_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"DeletedRiskListEntry":{"type":"object","properties":{"object":{"type":"string","enum":["risk_list_entry"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"]},"ForgottenRiskUser":{"type":"object","properties":{"object":{"type":"string","enum":["risk_user"]},"id":{"type":"string","description":"Your user id."},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"examples":[{"object":"risk_user","id":"u_42","deleted":true}]},"RiskSettings":{"type":"object","properties":{"object":{"type":"string","enum":["risk_settings"]},"review_threshold":{"type":"number","description":"Scores at or above it are `review`."},"block_threshold":{"type":"number","description":"Scores at or above it are `block`."},"disabled_reasons":{"type":"array","items":{"type":"string","enum":["email.invalid","email.disposable","email.undeliverable","email.role_account","email.typo","email.domain_new","ip.tor","ip.vpn_network","ip.hosting_provider","ip.vpn","ip.proxy","ip.relay","ip.private","velocity.signups_per_ip_1h","velocity.signups_per_ip_24h","velocity.signups_per_subnet_1h","velocity.signups_per_email_domain_1h","velocity.signups_per_mailbox_24h","velocity.signups_per_device_24h","velocity.checkouts_per_ip_1h","velocity.checkouts_per_user_1h","velocity.checkouts_per_card_24h","velocity.logins_per_ip_1h","velocity.logins_per_user_1h","velocity.events_per_ip_1h","velocity.events_per_user_1h","duplicate.canonical_mailbox","duplicate.device","history.fraud_mailbox","history.fraud_user","history.fraud_ip","history.fraud_subnet","history.fraud_card","history.fraud_device","checkout.card_country_mismatch","checkout.billing_country_mismatch","checkout.prepaid_card","device.automation","device.invalid","login.new_country","login.new_network","captcha.failed","captcha.missing"]},"description":"Reasons that never fire in this environment (they don't count in the score)."},"captcha":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["turnstile","hcaptcha"],"description":"The captcha provider."},"required":{"type":"boolean","description":"Whether assessments without a token get `captcha.missing`."}},"required":["provider","required"]},{"type":"null"}],"description":"The captcha provider assessments verify tokens with (never the secret)."},"content_thresholds":{"type":"object","properties":{"spam":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The score at which `content.spam` fires. `null`: never."},"phishing":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The score at which `content.phishing` fires. `null`: never."},"malware":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The score at which `content.malware` fires. `null`: never."},"fraud":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The score at which `content.fraud` fires. `null`: never."}},"required":["spam","phishing","malware","fraud"],"description":"Per content category, the score at which `content.<category>` fires; `null`: never (the score is still in `signals.content` for your rules)."},"reason_weights":{"type":"object","properties":{"email.invalid":{"type":"number","description":"This reason's weight in this environment."},"email.disposable":{"type":"number","description":"This reason's weight in this environment."},"email.undeliverable":{"type":"number","description":"This reason's weight in this environment."},"email.role_account":{"type":"number","description":"This reason's weight in this environment."},"email.typo":{"type":"number","description":"This reason's weight in this environment."},"email.domain_new":{"type":"number","description":"This reason's weight in this environment."},"ip.tor":{"type":"number","description":"This reason's weight in this environment."},"ip.vpn_network":{"type":"number","description":"This reason's weight in this environment."},"ip.hosting_provider":{"type":"number","description":"This reason's weight in this environment."},"ip.vpn":{"type":"number","description":"This reason's weight in this environment."},"ip.proxy":{"type":"number","description":"This reason's weight in this environment."},"ip.relay":{"type":"number","description":"This reason's weight in this environment."},"ip.private":{"type":"number","description":"This reason's weight in this environment."},"velocity.signups_per_ip_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.signups_per_ip_24h":{"type":"number","description":"This reason's weight in this environment."},"velocity.signups_per_subnet_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.signups_per_email_domain_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.signups_per_mailbox_24h":{"type":"number","description":"This reason's weight in this environment."},"velocity.signups_per_device_24h":{"type":"number","description":"This reason's weight in this environment."},"velocity.checkouts_per_ip_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.checkouts_per_user_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.checkouts_per_card_24h":{"type":"number","description":"This reason's weight in this environment."},"velocity.logins_per_ip_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.logins_per_user_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.events_per_ip_1h":{"type":"number","description":"This reason's weight in this environment."},"velocity.events_per_user_1h":{"type":"number","description":"This reason's weight in this environment."},"duplicate.canonical_mailbox":{"type":"number","description":"This reason's weight in this environment."},"duplicate.device":{"type":"number","description":"This reason's weight in this environment."},"history.fraud_mailbox":{"type":"number","description":"This reason's weight in this environment."},"history.fraud_user":{"type":"number","description":"This reason's weight in this environment."},"history.fraud_ip":{"type":"number","description":"This reason's weight in this environment."},"history.fraud_subnet":{"type":"number","description":"This reason's weight in this environment."},"history.fraud_card":{"type":"number","description":"This reason's weight in this environment."},"history.fraud_device":{"type":"number","description":"This reason's weight in this environment."},"checkout.card_country_mismatch":{"type":"number","description":"This reason's weight in this environment."},"checkout.billing_country_mismatch":{"type":"number","description":"This reason's weight in this environment."},"checkout.prepaid_card":{"type":"number","description":"This reason's weight in this environment."},"device.automation":{"type":"number","description":"This reason's weight in this environment."},"device.invalid":{"type":"number","description":"This reason's weight in this environment."},"login.new_country":{"type":"number","description":"This reason's weight in this environment."},"login.new_network":{"type":"number","description":"This reason's weight in this environment."},"captcha.failed":{"type":"number","description":"This reason's weight in this environment."},"captcha.missing":{"type":"number","description":"This reason's weight in this environment."},"content.spam":{"type":"number","description":"This reason's weight in this environment."},"content.phishing":{"type":"number","description":"This reason's weight in this environment."},"content.malware":{"type":"number","description":"This reason's weight in this environment."},"content.fraud":{"type":"number","description":"This reason's weight in this environment."}},"description":"Reasons whose weight this environment changed (from calibration or by hand); the rest weigh what the reason catalog says."},"updated_at":{"type":["string","null"],"format":"date-time","description":"`null` while on the defaults."}},"required":["object","review_threshold","block_threshold","disabled_reasons","captcha","content_thresholds","reason_weights","updated_at"],"examples":[{"object":"risk_settings","review_threshold":0.5,"block_threshold":0.85,"disabled_reasons":["email.role_account"],"captcha":{"provider":"turnstile","required":true},"content_thresholds":{"spam":null,"phishing":0.8,"malware":0.8,"fraud":0.9},"reason_weights":{"ip.hosting_provider":0.1},"updated_at":"2026-01-15T09:30:00.000Z"}]},"UpdateRiskSettingsRequest":{"type":"object","properties":{"review_threshold":{"type":"number","exclusiveMinimum":0,"maximum":1,"description":"Scores at or above it are `review`."},"block_threshold":{"type":"number","exclusiveMinimum":0,"maximum":1,"description":"Scores at or above it are `block`."},"disabled_reasons":{"type":"array","items":{"type":"string","enum":["email.invalid","email.disposable","email.undeliverable","email.role_account","email.typo","email.domain_new","ip.tor","ip.vpn_network","ip.hosting_provider","ip.vpn","ip.proxy","ip.relay","ip.private","velocity.signups_per_ip_1h","velocity.signups_per_ip_24h","velocity.signups_per_subnet_1h","velocity.signups_per_email_domain_1h","velocity.signups_per_mailbox_24h","velocity.signups_per_device_24h","velocity.checkouts_per_ip_1h","velocity.checkouts_per_user_1h","velocity.checkouts_per_card_24h","velocity.logins_per_ip_1h","velocity.logins_per_user_1h","velocity.events_per_ip_1h","velocity.events_per_user_1h","duplicate.canonical_mailbox","duplicate.device","history.fraud_mailbox","history.fraud_user","history.fraud_ip","history.fraud_subnet","history.fraud_card","history.fraud_device","checkout.card_country_mismatch","checkout.billing_country_mismatch","checkout.prepaid_card","device.automation","device.invalid","login.new_country","login.new_network","captcha.failed","captcha.missing"]},"maxItems":100,"description":"Reasons that never fire in this environment. Replaces the list."},"captcha":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["turnstile","hcaptcha"],"description":"The captcha provider."},"secret":{"type":"string","minLength":1,"maxLength":1024,"description":"The provider's secret key. Required when setting a provider for the first time or changing it; stored encrypted and never returned."},"required":{"type":"boolean","description":"Assessments without a `captcha` token get `captcha.missing`. Default false."}},"required":["provider"],"additionalProperties":false},{"type":"null"}],"description":"`null` turns captcha verification off and deletes the secret."},"content_thresholds":{"type":"object","properties":{"spam":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":1},{"type":"null"}],"description":"The score at which `content.spam` fires. `null` removes it."},"phishing":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":1},{"type":"null"}],"description":"The score at which `content.phishing` fires. `null` removes it."},"malware":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":1},{"type":"null"}],"description":"The score at which `content.malware` fires. `null` removes it."},"fraud":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":1},{"type":"null"}],"description":"The score at which `content.fraud` fires. `null` removes it."}},"additionalProperties":false,"description":"Changes the categories given: a score in (0, 1] sets the threshold, `null` removes it."},"reason_weights":{"type":"object","properties":{"email.invalid":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"email.disposable":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"email.undeliverable":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"email.role_account":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"email.typo":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"email.domain_new":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"ip.tor":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"ip.vpn_network":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"ip.hosting_provider":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"ip.vpn":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"ip.proxy":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"ip.relay":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"ip.private":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.signups_per_ip_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.signups_per_ip_24h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.signups_per_subnet_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.signups_per_email_domain_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.signups_per_mailbox_24h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.signups_per_device_24h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.checkouts_per_ip_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.checkouts_per_user_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.checkouts_per_card_24h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.logins_per_ip_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.logins_per_user_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.events_per_ip_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"velocity.events_per_user_1h":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"duplicate.canonical_mailbox":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"duplicate.device":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"history.fraud_mailbox":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"history.fraud_user":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"history.fraud_ip":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"history.fraud_subnet":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"history.fraud_card":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"history.fraud_device":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"checkout.card_country_mismatch":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"checkout.billing_country_mismatch":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"checkout.prepaid_card":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"device.automation":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"device.invalid":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"login.new_country":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"login.new_network":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"captcha.failed":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"captcha.missing":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"content.spam":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"content.phishing":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"content.malware":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."},"content.fraud":{"anyOf":[{"type":"number","minimum":0,"maximum":0.99},{"type":"null"}],"description":"This reason's new weight. `null` restores its default."}},"description":"Changes the reasons given: a weight in [0, 0.99] replaces the default, `null` goes back to it."}},"additionalProperties":false,"examples":[{"block_threshold":0.9,"captcha":{"provider":"turnstile","secret":"0x4AAA…","required":true}}]},"RiskCalibration":{"type":"object","properties":{"object":{"type":"string","enum":["risk_calibration"]},"window_days":{"type":"integer","description":"How many days back it looks."},"assessments":{"type":"integer","description":"Assessments in the window."},"labeled":{"type":"integer","description":"Of those, with feedback."},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/RiskCalibrationReason"},"description":"How each reason did against your feedback."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/RiskCalibrationRule"},"description":"How each rule did against your feedback."}},"required":["object","window_days","assessments","labeled","reasons","rules"],"description":"Feedback against the reasons and rules that fired, over the last 90 days. Feedback you give mostly on reviews and blocks over-represents those: read precision as a guide, not a measurement.","examples":[{"object":"risk_calibration","window_days":90,"assessments":1840,"labeled":212,"reasons":[{"code":"ip.hosting_provider","fired":96,"fraud":4,"legitimate":38,"precision":0.095,"default_weight":0.25,"weight":0.25,"suggested_weight":0.16}],"rules":[{"rule":"rskrule_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Disposable email from a data center","matched":31,"fraud":12,"legitimate":1,"precision":0.923}]}]},"RiskCalibrationReason":{"type":"object","properties":{"code":{"type":"string","enum":["email.invalid","email.disposable","email.undeliverable","email.role_account","email.typo","email.domain_new","ip.tor","ip.vpn_network","ip.hosting_provider","ip.vpn","ip.proxy","ip.relay","ip.private","velocity.signups_per_ip_1h","velocity.signups_per_ip_24h","velocity.signups_per_subnet_1h","velocity.signups_per_email_domain_1h","velocity.signups_per_mailbox_24h","velocity.signups_per_device_24h","velocity.checkouts_per_ip_1h","velocity.checkouts_per_user_1h","velocity.checkouts_per_card_24h","velocity.logins_per_ip_1h","velocity.logins_per_user_1h","velocity.events_per_ip_1h","velocity.events_per_user_1h","duplicate.canonical_mailbox","duplicate.device","history.fraud_mailbox","history.fraud_user","history.fraud_ip","history.fraud_subnet","history.fraud_card","history.fraud_device","checkout.card_country_mismatch","checkout.billing_country_mismatch","checkout.prepaid_card","device.automation","device.invalid","login.new_country","login.new_network","captcha.failed","captcha.missing","content.spam","content.phishing","content.malware","content.fraud"],"description":"The reason's code."},"fired":{"type":"integer","description":"Assessments it fired in."},"fraud":{"type":"integer","description":"With feedback `fraud` or `abuse`."},"legitimate":{"type":"integer","description":"With feedback `legitimate`."},"precision":{"type":["number","null"],"description":"`fraud / (fraud + legitimate)`: how often it was right when you told coss.com. `null` without feedback."},"default_weight":{"type":"number","description":"Its weight unless this environment changes it."},"weight":{"type":"number","description":"Its weight in this environment now."},"suggested_weight":{"type":["number","null"],"description":"The weight feedback supports: its precision, pulled toward the default while there is little feedback. `null` below 20 assessments with feedback."}},"required":["code","fired","fraud","legitimate","precision","default_weight","weight","suggested_weight"]},"RiskCalibrationRule":{"type":"object","properties":{"rule":{"type":"string","description":"The rule's id."},"name":{"type":"string","description":"The rule's name."},"matched":{"type":"integer","description":"Assessments it decided."},"fraud":{"type":"integer","description":"With feedback `fraud` or `abuse`."},"legitimate":{"type":"integer","description":"With feedback `legitimate`."},"precision":{"type":["number","null"],"description":"`fraud / (fraud + legitimate)`: how often it was right when you told coss.com. `null` without feedback."}},"required":["rule","name","matched","fraud","legitimate","precision"]},"RiskRule":{"type":"object","properties":{"object":{"type":"string","enum":["risk_rule"]},"id":{"type":"string"},"name":{"type":"string","description":"Your name for the rule, returned with reasons when it decides."},"enabled":{"type":"boolean","description":"`false`: it's kept, and no assessment applies it."},"position":{"type":"integer","description":"Rules are tried in ascending order."},"events":{"type":"array","items":{"$ref":"#/components/schemas/RiskEvent"},"description":"Events it applies to; empty: every event."},"match":{"type":"string","enum":["all","any"],"description":"`all`: every condition must hold. `any`: one is enough."},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RiskRuleCondition"},"description":"What must hold, by `match`."},"action":{"$ref":"#/components/schemas/RiskDecision"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","enabled","position","events","match","conditions","action","created_at","updated_at"],"examples":[{"object":"risk_rule","id":"rskrule_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Disposable email from a data center","enabled":true,"position":0,"events":["signup"],"match":"all","conditions":[{"field":"email.disposable","operator":"is","value":true},{"field":"ip.hosting","operator":"is","value":true}],"action":"block","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"RiskRuleCondition":{"type":"object","properties":{"field":{"type":"string","enum":["email.valid","email.disposable","email.undeliverable","email.role_account","email.free_provider","email.typo","email.domain_new","email.domain","email.domain_age_days","ip.tor","ip.hosting","ip.vpn","ip.proxy","ip.relay","ip.private","ip.country","ip.asn","ip.hosting_provider","captcha.passed","duplicate.canonical_mailbox","duplicate.device","history.fraud","login.new_country","login.new_network","content.spam","content.phishing","content.malware","content.fraud","checkout.amount","checkout.currency","checkout.card_country","checkout.card_funding","checkout.billing_country","checkout.shipping_country","device.automation","device.timezone","device.language","score","velocity.ip_1h","velocity.ip_24h","velocity.subnet_1h","velocity.subnet_24h","velocity.email_domain_1h","velocity.email_domain_24h","velocity.mailbox_1h","velocity.mailbox_24h","velocity.user_1h","velocity.user_24h","velocity.card_1h","velocity.card_24h","velocity.device_1h","velocity.device_24h"],"description":"The signal to test, such as `email.disposable` or `ip.country`."},"operator":{"type":"string","enum":["is","eq","neq","gt","gte","lt","lte","in","not_in"],"description":"How to compare. Booleans use `is`, numbers `eq` to `lte`, and strings `eq`, `neq`, `in` and `not_in`."},"value":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string","maxLength":320},{"type":"array","items":{"type":"string","maxLength":320},"minItems":1,"maxItems":100}],"description":"What to compare it with: its type follows the field, and `in` and `not_in` take a list of strings."}},"required":["field","operator","value"],"additionalProperties":false,"description":"A test of one field. A field without a value (no IP, no email…) never matches, whatever the operator."},"CreateRiskRuleRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Your name for the rule, returned with reasons when it decides."},"enabled":{"type":"boolean","description":"Default `true`."},"position":{"type":"integer","minimum":0,"maximum":10000,"description":"Default 0."},"events":{"type":"array","items":{"$ref":"#/components/schemas/RiskEvent"},"maxItems":5,"description":"Events it applies to. Default: every event."},"match":{"type":"string","enum":["all","any"],"description":"Default `all`."},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RiskRuleCondition"},"minItems":1,"maxItems":20,"description":"What must hold, by `match`."},"action":{"$ref":"#/components/schemas/RiskDecision"}},"required":["name","conditions","action"],"additionalProperties":false,"examples":[{"name":"Disposable email from a data center","events":["signup"],"conditions":[{"field":"email.disposable","operator":"is","value":true},{"field":"ip.hosting","operator":"is","value":true}],"action":"block"}]},"RiskRuleList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RiskRule"}},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"description":"Every rule of the environment (at most 50), in evaluation order.","examples":[{"object":"list","data":[{"object":"risk_rule","id":"rskrule_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"Disposable email from a data center","enabled":true,"position":0,"events":["signup"],"match":"all","conditions":[{"field":"email.disposable","operator":"is","value":true},{"field":"ip.hosting","operator":"is","value":true}],"action":"block","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"UpdateRiskRuleRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Your name for the rule."},"enabled":{"type":"boolean","description":"`false` keeps it, and stops applying it."},"position":{"type":"integer","minimum":0,"maximum":10000,"description":"Rules are tried in ascending order."},"events":{"type":"array","items":{"$ref":"#/components/schemas/RiskEvent"},"maxItems":5,"description":"Events it applies to. Empty: every event."},"match":{"type":"string","enum":["all","any"],"description":"`all`: every condition must hold. `any`: one is enough."},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/RiskRuleCondition"},"minItems":1,"maxItems":20,"description":"What must hold, by `match`."},"action":{"$ref":"#/components/schemas/RiskDecision"}},"additionalProperties":false,"examples":[{"enabled":false}]},"DeletedRiskRule":{"type":"object","properties":{"object":{"type":"string","enum":["risk_rule"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"]},"RiskEmailCheck":{"type":"object","properties":{"object":{"type":"string","enum":["risk_email_check"]},"email":{"type":"string","description":"The address checked."},"valid":{"type":"boolean","description":"Syntactically valid (the rest assumes it is)."},"domain":{"type":["string","null"],"description":"Its domain. `null` when it isn't valid."},"canonical":{"type":["string","null"],"description":"The mailbox with the provider's aliasing folded (dots and `+tags` at Gmail…): two addresses with the same canonical form reach one inbox."},"disposable":{"type":"boolean","description":"Whether its domain is a known burner service."},"deliverability":{"type":"string","enum":["deliverable","undeliverable","unknown"],"description":"From DNS (MX, A, AAAA). `unknown` when the lookup failed or timed out."},"role_account":{"type":"boolean","description":"Whether it's a role mailbox, like `info@`."},"free_provider":{"type":"boolean","description":"Whether its domain is a free mailbox provider."},"suggestion":{"type":["string","null"],"description":"The likely intended domain when this one looks like a typo of a popular one."},"domain_age_days":{"type":["integer","null"],"description":"Days since the domain was registered (RDAP); `null` when unknown or not looked up (free providers, disposable domains)."},"degraded":{"type":"array","items":{"type":"string","enum":["email_dns","domain_age"]},"description":"Lookups that failed or timed out (their fields are `unknown`/`null`)."}},"required":["object","email","valid","domain","canonical","disposable","deliverability","role_account","free_provider","suggestion","domain_age_days","degraded"],"examples":[{"object":"risk_email_check","email":"ada@gnail.com","valid":true,"domain":"gnail.com","canonical":"ada@gnail.com","disposable":false,"deliverability":"deliverable","role_account":false,"free_provider":false,"suggestion":"gmail.com","domain_age_days":7300,"degraded":[]}]},"RiskEmailCheckRequest":{"type":"object","properties":{"email":{"type":"string","minLength":1,"maxLength":320,"description":"The address to check, as given."}},"required":["email"],"additionalProperties":false,"examples":[{"email":"ada@gnail.com"}]},"RiskIpCheck":{"type":"object","properties":{"version":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]}],"description":"IPv4 or IPv6."},"private":{"type":"boolean","description":"Whether it's a private or reserved address."},"tor":{"type":"boolean","description":"Whether it's a Tor exit."},"hosting":{"type":"boolean","description":"Whether it's in a cloud, hosting or VPN network."},"hosting_provider":{"type":["string","null"],"description":"That network's operator. `null` when it isn't one."},"hosting_kind":{"type":["string","null"],"enum":["cloud","hosting","vpn",null],"description":"`cloud`, `hosting` or `vpn`. `null` when it isn't one."},"asn":{"type":["integer","null"],"description":"The network's autonomous system number. `null` when unknown."},"as_name":{"type":["string","null"],"description":"The network's name. `null` when unknown."},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2."},"privacy":{"anyOf":[{"$ref":"#/components/schemas/RiskIpPrivacy"},{"type":"null"}],"description":"From coss.com's IP privacy data provider (VPNs, proxies, relays). `null` when it isn't available or was not asked (private addresses)."},"object":{"type":"string","enum":["risk_ip_check"]},"ip":{"type":"string","description":"The address checked."},"degraded":{"type":"array","items":{"type":"string","enum":["ip_data","ip_privacy"]},"description":"`ip_data` when some IP data (Tor exits, cloud ranges, networks and countries) is unavailable at the moment; `ip_privacy` when the privacy data provider failed or timed out."}},"required":["version","private","tor","hosting","hosting_provider","hosting_kind","asn","as_name","country","privacy","object","ip","degraded"],"examples":[{"object":"risk_ip_check","ip":"185.220.101.1","version":4,"private":false,"tor":true,"hosting":false,"hosting_provider":null,"hosting_kind":null,"asn":60729,"as_name":"Stiftung Erneuerbare Freiheit","country":"DE","privacy":null,"degraded":[]}]},"RiskIpCheckRequest":{"type":"object","properties":{"ip":{"anyOf":[{"type":"string","format":"ip"},{"type":"string","format":"ip"}],"description":"The address to check."}},"required":["ip"],"additionalProperties":false,"examples":[{"ip":"185.220.101.1"}]},"RiskPhoneCheck":{"type":"object","properties":{"object":{"type":"string","enum":["risk_phone_check"]},"phone":{"type":"string","description":"The number in E.164, or as given when it isn't."},"valid":{"type":"boolean","description":"A possible number in its country's numbering plan. When the lookup failed (`degraded`), only the E.164 syntax was checked."},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2."},"line_type":{"type":["string","null"],"enum":["mobile","landline","fixed_voip","non_fixed_voip","toll_free","premium","shared_cost","personal","uan","voicemail","pager","unknown",null],"description":"`fixed_voip` numbers belong to an address (cable, business lines); `non_fixed_voip` ones can be had online in minutes (Google Voice, app numbers), the kind used for throwaway accounts. `null` when it couldn't be looked up."},"carrier":{"anyOf":[{"$ref":"#/components/schemas/RiskPhoneCarrier"},{"type":"null"}],"description":"The network the number is on now (after any port). `null` when unknown, and for toll-free, premium and personal numbers."},"sim_swap":{"anyOf":[{"$ref":"#/components/schemas/RiskPhoneSimSwap"},{"type":"null"}],"description":"The mobile number's last SIM change. `null` where coss.com doesn't have that data (not every country and carrier)."},"degraded":{"type":"array","items":{"type":"string","enum":["phone_data","sim_swap"]},"description":"`phone_data` when the lookup failed or timed out (or had no line type for the number); `sim_swap` when the carrier didn't answer about the SIM."}},"required":["object","phone","valid","country","line_type","carrier","sim_swap","degraded"],"examples":[{"object":"risk_phone_check","phone":"+14155550123","valid":true,"country":"US","line_type":"mobile","carrier":{"name":"T-Mobile USA, Inc.","mobile_country_code":"310","mobile_network_code":"260"},"sim_swap":null,"degraded":[]}]},"RiskPhoneCarrier":{"type":"object","properties":{"name":{"type":["string","null"]},"mobile_country_code":{"type":["string","null"]},"mobile_network_code":{"type":["string","null"],"description":"Only for mobile numbers."}},"required":["name","mobile_country_code","mobile_network_code"]},"RiskPhoneSimSwap":{"type":"object","properties":{"recent":{"type":"boolean","description":"The SIM changed within `period`: someone may have taken the number over."},"swapped_at":{"type":["string","null"],"description":"The last SIM change, where the carrier tells the date."},"period":{"type":["string","null"],"description":"What `recent` means, as an ISO 8601 duration (`PT48H`)."}},"required":["recent","swapped_at","period"]},"RiskPhoneCheckRequest":{"type":"object","properties":{"phone":{"type":"string","minLength":1,"maxLength":32,"description":"The number in E.164 (`+14155550123`); spaces, dashes, dots and brackets are ignored. Anything else is `valid: false`."}},"required":["phone"],"additionalProperties":false,"examples":[{"phone":"+14155550123"}]},"RiskContentClassification":{"type":"object","properties":{"object":{"type":"string","enum":["risk_content_classification"]},"scores":{"$ref":"#/components/schemas/RiskContentSignals"},"truncated":{"type":"boolean","description":"The text was longer than the model reads: only its beginning was classified."}},"required":["object","scores","truncated"],"description":"Scores only: coss.com never decides what they mean for you. Neither the text nor the scores are stored.","examples":[{"object":"risk_content_classification","scores":{"spam":0.91,"phishing":0.04,"malware":0.01,"fraud":0.86},"truncated":false}]},"RiskContentClassifyRequest":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":50000,"description":"The text to classify (a profile bio, a comment, a listing). The model reads the first 8,000 characters."}},"required":["text"],"additionalProperties":false,"examples":[{"text":"Earn $5,000 a week from home! DM me on Telegram: t.me/fast-cash"}]},"RiskLimit":{"type":"object","properties":{"object":{"type":"string","enum":["risk_limit"]},"bucket":{"type":"string","description":"The bucket's name."},"allowed":{"type":"boolean","description":"Whether to let the request through. Denied requests take no tokens."},"limit":{"type":"integer","description":"The bucket's size (`burst`)."},"remaining":{"type":"integer","description":"Tokens left for this key."},"reset_ms":{"type":"integer","description":"Milliseconds until the key's bucket is full again."},"retry_after_ms":{"type":["integer","null"],"description":"When denied: milliseconds until the same request would be allowed; `null` when it never would (`cost` above the bucket's size). 0 when allowed."},"degraded":{"type":"boolean","description":"coss.com couldn't count (its store was unavailable): `allowed` is the bucket's `on_failure`."}},"required":["object","bucket","allowed","limit","remaining","reset_ms","retry_after_ms","degraded"],"examples":[{"object":"risk_limit","bucket":"password_reset","allowed":true,"limit":5,"remaining":4,"reset_ms":720000,"retry_after_ms":0,"degraded":false}]},"CheckRiskLimitRequest":{"type":"object","properties":{"bucket":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$","description":"The bucket's name."},"key":{"type":"string","minLength":1,"maxLength":512,"description":"Who or what is limited: a user id, an email address, an IP address… coss.com keeps only a keyed hash of it."},"cost":{"type":"integer","minimum":1,"maximum":1000000,"description":"Tokens this request takes. Default 1."}},"required":["bucket","key"],"additionalProperties":false,"examples":[{"bucket":"password_reset","key":"ada@example.com"}]},"RiskLimitBucket":{"type":"object","properties":{"object":{"type":"string","enum":["risk_limit_bucket"]},"id":{"type":"string","examples":["rsklb_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"name":{"type":"string","description":"What `POST /v1/risk/limits` names it by."},"limit":{"type":"integer","description":"Tokens added per `period_seconds`."},"period_seconds":{"type":"integer","description":"How many seconds `limit` tokens take to be added."},"burst":{"type":"integer","description":"The bucket's size: how many requests a key can make at once."},"on_failure":{"type":"string","enum":["allow","deny"],"description":"The answer while coss.com can't count (its store is unavailable): `allow` (fail open) or `deny`."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","limit","period_seconds","burst","on_failure","created_at","updated_at"],"examples":[{"object":"risk_limit_bucket","id":"rsklb_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"password_reset","limit":5,"period_seconds":3600,"burst":5,"on_failure":"allow","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}]},"CreateRiskLimitBucketRequest":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$","description":"Unique in the environment; can't be changed."},"limit":{"type":"integer","minimum":1,"maximum":1000000,"description":"Tokens added per `period_seconds`."},"period_seconds":{"type":"integer","minimum":1,"maximum":86400,"description":"1 second to 1 day."},"burst":{"type":"integer","minimum":1,"maximum":1000000,"description":"How many requests a key can make at once. Defaults to `limit`."},"on_failure":{"type":"string","enum":["allow","deny"],"description":"The answer while coss.com can't count. Defaults to `allow`."}},"required":["name","limit","period_seconds"],"additionalProperties":false,"examples":[{"name":"password_reset","limit":5,"period_seconds":3600}]},"RiskLimitBucketList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RiskLimitBucket"}},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"description":"Every bucket of the environment (at most 100), by name.","examples":[{"object":"list","data":[{"object":"risk_limit_bucket","id":"rsklb_01k7c8m4q2f3e9v6t5r1n0p8yz","name":"password_reset","limit":5,"period_seconds":3600,"burst":5,"on_failure":"allow","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z"}],"has_more":false}]},"UpdateRiskLimitBucketRequest":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":1000000,"description":"Tokens added per `period_seconds`."},"period_seconds":{"type":"integer","minimum":1,"maximum":86400,"description":"How many seconds `limit` tokens take to be added."},"burst":{"type":"integer","minimum":1,"maximum":1000000,"description":"The bucket's size: how many requests a key can make at once."},"on_failure":{"type":"string","enum":["allow","deny"],"description":"The answer while coss.com can't count: `allow` or `deny`."}},"additionalProperties":false,"examples":[{"limit":10,"burst":20}]},"DeletedRiskLimitBucket":{"type":"object","properties":{"object":{"type":"string","enum":["risk_limit_bucket"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"]}},"parameters":{"CossVersion":{"in":"header","name":"Coss-Version","required":false,"description":"The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.","schema":{"type":"string","enum":["2026-10-10"],"examples":["2026-10-10"]}}}},"paths":{"/v1/environment":{"get":{"operationId":"getEnvironment","tags":["Environment"],"summary":"Retrieve the API key's environment","description":"Which environment, project and organization the API key belongs to, and the key itself. Any valid key can read its own environment (no permission needed): use it to check a key, show where it sends and what it may do.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The API key's environment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Environment"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/api_key":{"delete":{"operationId":"revokeApiKey","tags":["Environment"],"summary":"Revoke the API key","description":"Revokes the API key making this request, at once: every later request with it fails with `invalid_api_key`. `coss logout --revoke` uses it. Other keys are revoked in the dashboard. With an OIDC access token, revokes only that token: its credential keeps working.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The key was revoked.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedApiKey"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/oidc/token":{"post":{"operationId":"exchangeOidcToken","tags":["Environment"],"summary":"Exchange an OIDC token","description":"Exchanges an OIDC ID token from a CI or hosting provider (GitHub Actions, Vercel, GitLab, CircleCI or any issuer an environment trusts) for a short-lived access token, so no API key has to be stored there. The token must come from the credential's issuer, be issued for its audience and meet every condition on its claims. Needs no API key. Every refusal is the same `invalid_oidc_token`; the reason is in the environment's logs. `DELETE /v1/api_key` with the access token revokes just that token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeOidcTokenBody"}}}},"responses":{"201":{"description":"The access token.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OidcAccessToken"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The ID token wasn't accepted for this credential, or the credential doesn't exist (`invalid_oidc_token`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential's organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body is invalid (`invalid_request_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many exchanges for this credential or from this address, or too many refused tokens from this address. Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The token couldn't be checked right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/emails":{"post":{"operationId":"sendEmail","tags":["Emails"],"summary":"Send an email","description":"Queues an email from the API key's environment and returns it with `status: \"queued\"`; it is handed to the delivery provider moments later. Follow it with `GET /v1/emails/{id}` or the `email.sent` / `email.failed` webhooks. Live (`coss_live_…`) keys must send from a verified domain of the organization. Sandbox (`coss_test_…`) keys accept any `from` and never deliver anything; the response has `sandbox: true`. Recipients on the environment's suppression list (for every email, or for the email's `category`) are skipped and get the status `suppressed`. With a future `scheduled_at` the email is stored with the status `scheduled` and sent at that time; the domain and the suppression list are checked again then. Attachments are base64-encoded; only metadata is kept after sending. Recipients count against the organization's send quota (per second and per day; sandbox environments have their own daily quota). With open or click tracking on (the environment's settings, or `tracking`), the HTML body is delivered with a tracking pixel and/or links rewritten to coss.com redirects; the stored `html` stays as sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailRequest"}}}},"responses":{"202":{"description":"The email, accepted for delivery (`queued` or `scheduled`). A replay returns the original email with its current status.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live sending is paused for an overdue invoice or the spend limit (`billing_hold`), or the send would go past the plan's monthly allowance (`usage_limit_exceeded`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`insufficient_permissions`), its organization is suspended (`organization_suspended`), live sending is suspended (`account_suspended`), or sending is paused for the organization because of its sending reputation (`sending_paused`), or the `subaccount` is turned off (`subaccount_disabled`) or paused (`subaccount_paused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), the `from` domain is not a verified domain of the organization (`domain_not_verified`, live keys only), the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`), or the template can't be sent: it doesn't exist (`template_not_found`), has no published version (`template_not_published`) or no such version (`template_version_not_found`), the variables don't match it (`invalid_template_variables`, see `issues`), or it renders an invalid subject or empty body (`template_render_failed`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or the email's recipients exceed the send quota (`quota_exceeded`). Retry after `Retry-After` seconds; without `Retry-After` the email has more recipients than the quota allows at once.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listEmails","tags":["Emails"],"summary":"List emails","description":"Emails sent from the API key's environment, newest first, without their content (retrieve an email for `html`, `text`, `headers` and `attachments`). Filter by recipient (`to`), by the email's or a recipient's status, by category, batch or creation time. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":320,"description":"Only emails with this recipient (in `to`, `cc` or `bcc`; the bare address, any case).","examples":["user@example.com"]},"required":false,"description":"Only emails with this recipient (in `to`, `cc` or `bcc`; the bare address, any case).","name":"to","in":"query"},{"schema":{"type":"string","description":"Only emails with a recipient in one of these statuses, comma-separated: `bounced,complained`. With `to`, that recipient's status."},"required":false,"description":"Only emails with a recipient in one of these statuses, comma-separated: `bounced,complained`. With `to`, that recipient's status.","name":"recipient_status","in":"query"},{"schema":{"type":"string","description":"Only emails in these statuses, comma-separated: `failed`."},"required":false,"description":"Only emails in these statuses, comma-separated: `failed`.","name":"status","in":"query"},{"schema":{"type":"string","maxLength":256,"description":"Free text, matched against the subject and the `to` addresses."},"required":false,"description":"Free text, matched against the subject and the `to` addresses.","name":"q","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"Only emails of this category."},"required":false,"description":"Only emails of this category.","name":"category","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only the emails of this batch."},"required":false,"description":"Only the emails of this batch.","name":"batch_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Only the emails sent for this sub-account (its id or your uid)."},"required":false,"description":"Only the emails sent for this sub-account (its id or your uid).","name":"subaccount","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only emails created at or after this time."},"required":false,"description":"Only emails created at or after this time.","name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only emails created before this time."},"required":false,"description":"Only emails created before this time.","name":"created_before","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last email of the previous page."},"required":false,"description":"Cursor: the `id` of the last email of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of emails.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSummaryList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/batch":{"post":{"operationId":"sendEmailBatch","tags":["Emails"],"summary":"Send a batch of emails","description":"Queues up to 100 emails in one request. Each email is handled exactly as by `POST /v1/emails` (sender checks, suppressions, scheduling, attachments, tracking), but the batch is all or nothing: if any email is invalid, or any `from` is not a verified domain (live keys), nothing is stored and the error names the email (e.g. `emails.3.to`). One `Idempotency-Key` covers the whole batch. The emails' recipients are charged against the send quota together, so a batch with more recipients than the quota allows at once is refused (`quota_exceeded` without `Retry-After`): split it. The request body shares the 40 MB limit of a single send.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original email (with its current status) instead of sending again, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailBatchRequest"}}}},"responses":{"202":{"description":"The batch, accepted for delivery, with its emails in request order. A replay returns the original batch with the emails' current statuses.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBatch"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live sending is paused for an overdue invoice or the spend limit (`billing_hold`), or the send would go past the plan's monthly allowance (`usage_limit_exceeded`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`insufficient_permissions`), its organization is suspended (`organization_suspended`), live sending is suspended (`account_suspended`), sending is paused for the organization because of its sending reputation (`sending_paused`), or a `subaccount` is turned off (`subaccount_disabled`) or paused (`subaccount_paused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), a `from` domain is not a verified domain of the organization (`domain_not_verified`, live keys only; `param` names the email), the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`), or an email's template can't be sent (the `template_…` codes of `POST /v1/emails`; `param` names the email).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or the batch's recipients exceed the send quota (`quota_exceeded`). Retry after `Retry-After` seconds; without `Retry-After` the batch has more recipients than the quota allows at once.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/batch/{id}":{"get":{"operationId":"getEmailBatch","tags":["Emails"],"summary":"Retrieve a batch of emails","description":"A batch sent with `POST /v1/emails/batch`, with its emails' current statuses in the order of the request. Emails past the data retention period are left out. Only batches sent from the API key's own environment can be retrieved.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The batch's id (`batch_id` of its emails).","examples":["batch_01k8d0n6x5f3w2e1r9t7y4u6i8"]},"required":true,"description":"The batch's id (`batch_id` of its emails).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The batch.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailBatch"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No batch with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}":{"get":{"operationId":"getEmail","tags":["Emails"],"summary":"Retrieve an email","description":"Only emails sent from the API key's own environment can be retrieved.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The email.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/cancel":{"post":{"operationId":"cancelEmail","tags":["Emails"],"summary":"Cancel a scheduled email","description":"Cancels an email sent with a future `scheduled_at` before it is sent. Canceling an already canceled email returns it unchanged. To send it at another time, reschedule it instead.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The canceled email.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The email is not scheduled (it is being sent, was sent or failed): `email_not_cancelable`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/reschedule":{"post":{"operationId":"rescheduleEmail","tags":["Emails"],"summary":"Reschedule a scheduled email","description":"Moves an email sent with a future `scheduled_at` to a new time, at most 30 days from now, and records an `email.rescheduled` event. A time that is not in the future sends it within seconds. Rescheduling to the time it already has returns it unchanged. The domain and the suppression list are still checked when it is sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescheduleEmailRequest"}}}},"responses":{"200":{"description":"The rescheduled email.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Email"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), or the email is not scheduled (it is being sent, was sent, failed or was canceled): `email_not_reschedulable`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/events":{"get":{"operationId":"listEmailEvents","tags":["Emails"],"summary":"List an email's delivery events","description":"Every delivery event of the email, oldest first: `email.scheduled`, `email.rescheduled`, `email.canceled`, `email.sent` and `email.failed` for the whole email, and `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained` and `email.suppressed` (skipped because of the suppression list) per recipient, plus `email.opened` and `email.clicked` when tracking is on (attributed to a recipient only when the email had a single one) and `email.unsubscribed` after a one-click unsubscribe.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last event id of the previous page."},"required":false,"description":"The last event id of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The email's events.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailEventList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/emails/{id}/links":{"get":{"operationId":"listEmailLinks","tags":["Emails"],"summary":"List an email's tracked links","description":"The links coss.com rewrote for click tracking, in the order they appear in the HTML, with their click counts. Empty unless the email was sent with click tracking.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The email's id.","examples":["email_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The email's tracked links.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailLinkList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No email with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates":{"post":{"operationId":"createEmailTemplate","tags":["Email templates"],"summary":"Create an email template","description":"Creates a template with a draft holding its variables and a subject, HTML and text per locale. Sends use it once its draft is published. Not idempotent: retrying after a lost response can create a second template (unless it has an `alias`). Templates belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones. Give a template the same `alias` in every environment to send it by that name.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmailTemplateRequest"}}}},"responses":{"200":{"description":"The template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), another template has the alias (`template_alias_taken`), or the environment has 500 templates (`template_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listEmailTemplates","tags":["Email templates"],"summary":"List email templates","description":"The environment's templates, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last template of the previous page."},"required":false,"description":"Cursor: the `id` of the last template of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of templates.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates/{id}":{"get":{"operationId":"getEmailTemplate","tags":["Email templates"],"summary":"Retrieve an email template","description":"A template by id or alias. Its content is in its draft and versions.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateEmailTemplate","tags":["Email templates"],"summary":"Update an email template","description":"Changes the template's name, alias or description. Changing the alias changes what sends must use. Content changes go to the draft (`PUT /v1/email_templates/{id}/draft`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailTemplateRequest"}}}},"responses":{"200":{"description":"The template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or another template has the alias (`template_alias_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteEmailTemplate","tags":["Email templates"],"summary":"Delete an email template","description":"Deletes the template with its draft and every version. Emails already sent or scheduled from it keep their content; new sends naming it fail with `template_not_found`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The template was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedEmailTemplate"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates/{id}/draft":{"get":{"operationId":"getEmailTemplateDraft","tags":["Email templates"],"summary":"Retrieve a template's draft","description":"The draft (`version: null`): what the next publish makes sends use. `problems` lists syntax errors and undeclared variables, which keep it from being published.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The draft.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateVersion"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateEmailTemplateDraft","tags":["Email templates"],"summary":"Update a template's draft","description":"Replaces the draft's variables and content. Sends keep using the published version until the draft is published. Pass the `revision` you read to refuse overwriting someone else's changes. A draft with problems is saved (and reported in `problems`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailTemplateDraftRequest"}}}},"responses":{"200":{"description":"The saved draft.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateVersion"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or the draft changed since `revision` (`template_revision_mismatch`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates/{id}/publish":{"post":{"operationId":"publishEmailTemplate","tags":["Email templates"],"summary":"Publish a template's draft","description":"Copies the draft into the next version, which sends use from then on. Emails already accepted keep the content they were rendered with. A draft without changes since the last publish returns that version, so retrying with the `revision` you reviewed is safe (without it, a retry could publish edits saved in between).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishEmailTemplateRequest"}}}},"responses":{"200":{"description":"The published version.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateVersion"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The draft has problems or no content for its default locale (`template_invalid`, see `issues`), or changed since `revision` (`template_revision_mismatch`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates/{id}/render":{"post":{"operationId":"renderEmailTemplate","tags":["Email templates"],"summary":"Render a template","description":"Renders the draft (or a published `version`) with `variables`, exactly as a send would, and returns the subject, HTML and text: a preview, nothing is sent or stored. Without `variables` it renders the version's `sample_variables`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderEmailTemplateRequest"}}}},"responses":{"200":{"description":"The rendered template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderedEmailTemplate"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the draft has problems (`template_invalid`, see `issues`), the variables don't match its declarations (`invalid_template_variables`), it has no such version (`template_version_not_found`), or it doesn't render (`template_render_failed`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates/{id}/versions":{"get":{"operationId":"listEmailTemplateVersions","tags":["Email templates"],"summary":"List a template's versions","description":"Published versions, newest first. Pass the last `version` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":20,"description":"1-20, default 10."},"required":false,"description":"1-20, default 10.","name":"limit","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"Cursor: the `version` of the last version of the previous page."},"required":false,"description":"Cursor: the `version` of the last version of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of versions.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateVersionList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates/{id}/versions/{version}":{"get":{"operationId":"getEmailTemplateVersion","tags":["Email templates"],"summary":"Retrieve a template version","description":"A published version, which never changes.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"A published version number.","examples":[1]},"required":true,"description":"A published version number.","name":"version","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The version.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateVersion"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment, or it has no such version (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email_templates/{id}/versions/{version}/restore":{"post":{"operationId":"restoreEmailTemplateVersion","tags":["Email templates"],"summary":"Restore a template version","description":"Replaces the draft with a published version's variables and content. Publish the draft to make sends use it again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id or alias.","examples":["etpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id or alias.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"A published version number.","examples":[1]},"required":true,"description":"A published version number.","name":"version","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The draft.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateVersion"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id or alias exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The template has no such version (`template_version_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains":{"post":{"operationId":"createDomain","tags":["Domains"],"summary":"Add a sending domain","description":"Claims the domain for the organization and returns the DNS records to publish. Domains belong to the organization, not to one environment, so every API key of the organization sees the same domains. The records are checked repeatedly in the background and verification gives up after 72 hours; until the domain is `verified`, live keys cannot send from it.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDomainRequest"}}}},"responses":{"200":{"description":"The domain, with the DNS records to publish.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan allows no more domains (`plan_limit_reached`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the name is not a usable domain (`invalid_domain`), it is already in use here or by another account (`domain_taken`), or The organization already has 5 domains awaiting verification (`too_many_pending_domains`). For a sub-account: it doesn't exist in the API key's environment (`subaccount_not_found`), isn't live (`subaccount_not_live`), or has 10 domains already (`too_many_subaccount_domains`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The delivery provider could not set the domain up; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listDomains","tags":["Domains"],"summary":"List sending domains","description":"Every domain of the organization, ordered by name. Domains belong to the organization, not to one environment, so every API key of the organization sees the same domains.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Only this sub-account's domains (its id or your uid)."},"required":false,"description":"Only this sub-account's domains (its id or your uid).","name":"subaccount","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The organization's domains.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`subaccount` names no sub-account of the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}":{"patch":{"operationId":"updateDomain","tags":["Domains"],"summary":"Update a sending domain","description":"Shares one of the organization's own domains with its sub-accounts (they may then send from it, through the organization's reputation), or stops sharing it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDomainRequest"}}}},"responses":{"200":{"description":"The domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or the domain is a sub-account's (`not_shareable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getDomain","tags":["Domains"],"summary":"Retrieve a sending domain","description":"The domain with the result of the last DNS check, so you can show which records are still missing or mismatched.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDomain","tags":["Domains"],"summary":"Remove a sending domain","description":"Removes the domain and its provider identity. Emails already sent are unaffected, but live keys can no longer send from it and the name becomes available again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDomain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The organization's single sign-on uses the domain (`domain_in_use_by_sso`): remove it from the SSO provider in the dashboard first.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The delivery provider could not remove the domain; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/verify":{"post":{"operationId":"verifyDomain","tags":["Domains"],"summary":"Check a domain's DNS records now","description":"Asks the delivery provider and DNS about the domain immediately instead of waiting for the next background check, and returns the updated domain. A `failed` domain starts verification over with fresh DKIM records, which have to be published again. Its tracking domain, if any, is checked too (and set up again if it `failed`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain, as the check left it.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The organization already has 5 domains awaiting verification, so a `failed` one cannot restart (`too_many_pending_domains`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The domain was checked moments ago (`domain_recently_checked`), or too many requests with this API key (`rate_limited`). Retry after `Retry-After` seconds, or just read the domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The delivery provider could not be reached; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/tracking":{"post":{"operationId":"createTrackingDomain","tags":["Domains"],"summary":"Add a custom tracking domain","description":"Sets up a subdomain of the domain (e.g. `links.acme.com`) to serve open and click tracking. Publish the CNAME record in `tracking.record`; coss.com then issues its certificate and checks it in the background, giving up after 72 hours. Open pixels and click redirects of emails sent from the domain (or its subdomains without a domain of their own) use the tracking domain while it is `active`, and the default tracking host otherwise. A domain has at most one tracking domain: remove it to use another hostname.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTrackingDomainRequest"}}}},"responses":{"200":{"description":"The domain, with its tracking domain and the CNAME to publish.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include custom tracking domains (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the hostname is not a subdomain of the domain it can use (`invalid_tracking_hostname`), the domain already has a tracking domain (`tracking_domain_exists`), or the hostname is already in use (`tracking_domain_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The certificate provider could not set the hostname up; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTrackingDomain","tags":["Domains"],"summary":"Remove a custom tracking domain","description":"Removes the domain's tracking domain. Later emails use the default tracking host, but links and open pixels in emails already sent through the tracking domain stop working.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain, without a tracking domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization, or it has no tracking domain (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The certificate provider could not remove the hostname; retry (`provider_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/receiving":{"post":{"operationId":"createReceivingDomain","tags":["Domains"],"summary":"Receive email at a domain","description":"Starts receiving email at the domain itself or a subdomain (e.g. `inbound.acme.com`): email sent to any address at that hostname becomes a received email of the API key's environment (an `email.received` webhook, `GET /v1/received_emails`). Publish the MX record in `receiving.record`; coss.com checks it in the background. Using the domain itself moves all of its mail to coss.com. A domain has at most one receiving hostname: remove it to use another one.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReceivingDomainRequest"}}}},"responses":{"200":{"description":"The domain, with its receiving domain and the MX record to publish.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the hostname is not one the domain can receive at (`invalid_receiving_hostname`), the domain already receives email (`receiving_domain_exists`), the hostname is already in use (`receiving_domain_taken`), or this deployment does not receive email (`receiving_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteReceivingDomain","tags":["Domains"],"summary":"Stop receiving email at a domain","description":"Stops receiving at the domain's receiving hostname: later mail to it is dropped (remove the MX record too). Emails already received stay until their retention ends.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain, without a receiving domain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization, or it does not receive email (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/dmarc":{"get":{"operationId":"getDomainDmarc","tags":["Domains"],"summary":"Retrieve a domain's DMARC status","description":"The domain's published DMARC record, where it is on the path from `p=none` to `p=reject`, the record to publish next and whether the last 14 days of aggregate reports say that is safe (`ready`, with the `checks` behind it), and a summary of those reports. Mailbox providers send DMARC aggregate reports to the domain's `report_address` once its `_dmarc` record names it (`rua=mailto:…`), usually once a day each.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The domain's DMARC status.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainDmarc"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/dmarc/reports":{"get":{"operationId":"listDomainDmarcReports","tags":["Domains"],"summary":"List a domain's DMARC reports","description":"The aggregate reports received about the domain, newest first, without their rows (retrieve one for those). Pass the last `id` as `after` to get the next page while `has_more` is true. Mailbox providers send DMARC aggregate reports to the domain's `report_address` once its `_dmarc` record names it (`rua=mailto:…`), usually once a day each.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last report of the previous page."},"required":false,"description":"Cursor: the `id` of the last report of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of DMARC reports.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DmarcReportList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No domain with this id exists in this organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{id}/dmarc/reports/{report_id}":{"get":{"operationId":"getDomainDmarcReport","tags":["Domains"],"summary":"Retrieve a DMARC report","description":"One aggregate report with its rows: each source IP, how many messages it sent, whether they passed DMARC (aligned DKIM or SPF) and what the receiver did with them.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The domain's id.","examples":["dom_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The domain's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The report's id.","examples":["dmarcrep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The report's id.","name":"report_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The report.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DmarcReport"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such domain in this organization, or no such report of it (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/dedicated_ips":{"get":{"operationId":"getDedicatedIpPool","tags":["Dedicated IPs"],"summary":"Retrieve the organization's dedicated IPs","description":"The organization's dedicated IP pool (the Dedicated IPs add-on, bought on the dashboard's billing page): its status, its IPs and how much of the last week's mail they delivered. Organization-wide, like domains: every environment's key sees the same pool; only live emails go through it. Without the add-on the status is `not_enabled`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The organization's dedicated IPs.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DedicatedIpPool"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/webhook_endpoints":{"post":{"operationId":"createWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Create a webhook endpoint","description":"Registers a URL that receives signed event notifications. Webhook endpoints belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox endpoints, and a `coss_live_…` key only production ones. The response carries the signing secret, which is returned only here and when it is rolled: store it, and verify every delivery with it (`verifyWebhook` in the SDK).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"The endpoint and its signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, including an unknown `api_version`), the URL is not a usable https:// URL (`invalid_url`), or the environment already has 10 endpoints (`too_many_endpoints`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listWebhookEndpoints","tags":["Webhook endpoints"],"summary":"List webhook endpoints","description":"Every endpoint of the API key's environment, oldest first. Webhook endpoints belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox endpoints, and a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's webhook endpoints.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/webhook_endpoints/{id}":{"get":{"operationId":"getWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Retrieve a webhook endpoint","description":"The endpoint without its signing secret, which is only returned when created or rolled.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The webhook endpoint.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Update a webhook endpoint","description":"Changes the URL, description, subscribed event types, API version or `enabled` flag. Omitted fields keep their current value, and the signing secret stays the same (see Roll a signing secret), so receivers keep verifying deliveries. Disabling an endpoint stops deliveries without losing its configuration.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"The updated endpoint.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`) or the URL is not a usable https:// URL (`invalid_url`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Delete a webhook endpoint","description":"Removes the endpoint and its delivery log. Deliveries already queued for it are dropped. To stop deliveries temporarily, set `enabled` to `false` instead.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The endpoint was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedWebhookEndpoint"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/roll_secret":{"post":{"operationId":"rollWebhookEndpointSecret","tags":["Webhook endpoints"],"summary":"Roll a signing secret","description":"Replaces the endpoint's signing secret with a new one, returned in the response (the only time it is). Until `previous_secret_expires_at`, every delivery is signed with both secrets (`webhook-signature` lists two signatures), so receivers verifying with either one accept it: deploy the new secret, then let the old one expire. Rolling again in that time stops the older secret at once. Not idempotent: after a lost response, roll again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RollWebhookEndpointSecretRequest"}}}},"responses":{"200":{"description":"The endpoint and its new signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/recover":{"post":{"operationId":"recoverWebhookEndpoint","tags":["Webhook endpoints"],"summary":"Recover failed deliveries","description":"Queues the endpoint's deliveries that `failed` since `since` for one more attempt each, oldest first, spread over the next minute, e.g. after fixing a receiver that was down. At most 1000 per call: while `has_more` is `true`, call again with the same `since`. The endpoint must be enabled.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoverWebhookEndpointRequest"}}}},"responses":{"200":{"description":"How many deliveries were queued.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointRecovery"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or the endpoint is disabled (`endpoint_disabled`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhook endpoints"],"summary":"List an endpoint's deliveries","description":"The endpoint's delivery log, newest first: one delivery per event sent to it, with every HTTP attempt and the payload as sent. Pass the last `id` as `after` to get the next page while `has_more` is true. Deleting the endpoint deletes its log.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"schema":{"type":"string","enum":["pending","succeeded","failed"],"description":"Only deliveries with this status."},"required":false,"description":"Only deliveries with this status.","name":"status","in":"query"},{"schema":{"type":"string","description":"Only the delivery of this event."},"required":false,"description":"Only the delivery of this event.","name":"event_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last delivery of the previous page."},"required":false,"description":"Cursor: the `id` of the last delivery of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of deliveries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/deliveries/{delivery_id}":{"get":{"operationId":"getWebhookDelivery","tags":["Webhook endpoints"],"summary":"Retrieve a delivery","description":"One delivery of the endpoint, with every HTTP attempt and the payload as sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The delivery's id.","examples":["whdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"required":true,"description":"The delivery's id.","name":"delivery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delivery.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment, or the endpoint has no delivery with this id (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_endpoints/{id}/deliveries/{delivery_id}/retry":{"post":{"operationId":"retryWebhookDelivery","tags":["Webhook endpoints"],"summary":"Retry a delivery","description":"Queues a finished delivery (`succeeded` or `failed`) for one more attempt, made within seconds, signed with the endpoint's current secret and sent to its current URL. A delivery that is still `pending` is returned unchanged: it is already scheduled for `next_attempt_at` (automatic retries stop after 8 attempts).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook endpoint's id.","examples":["whep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook endpoint's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The delivery's id.","examples":["whdel_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"required":true,"description":"The delivery's id.","name":"delivery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delivery, now `pending`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No webhook endpoint with this id exists in the API key's environment, or the endpoint has no delivery with this id (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_listeners":{"post":{"operationId":"createWebhookListener","tags":["Webhook endpoints"],"summary":"Open a webhook listener","description":"Listeners are how `coss listen` forwards events to a local server: coss.com can't reach `localhost`, so the CLI pulls them. They belong to the API key's environment, receive events created after they open, and don't count toward the plan's webhook endpoints. A listener closes when it is deleted or after 10 minutes without a poll; an environment has at most 5 open at once. Events reach it unsigned: the CLI signs what it forwards with its own secret.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookListenerRequest"}}}},"responses":{"200":{"description":"The listener.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListener"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, including an unknown `api_version`), or the environment already has 5 open listeners (`too_many_listeners`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/webhook_listeners/{id}/poll":{"post":{"operationId":"pollWebhookListener","tags":["Webhook endpoints"],"summary":"Poll a webhook listener","description":"Acknowledges deliveries handed out earlier, keeps the listener open for another 10 minutes, and waits up to `wait_ms` (at most 25 s) for events. Deliveries come oldest first; one not acknowledged within two minutes is handed out again (with the same `event_id`). The answer may come early, with no deliveries, when the API restarts: poll again. Polls are not request-logged; each acknowledgement is logged as a `webhook.forward` line.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook listener's id.","examples":["whlis_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook listener's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PollWebhookListenerRequest"}}}},"responses":{"200":{"description":"Deliveries to forward (possibly none).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListenerPoll"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No open webhook listener with this id exists in the API key's environment: it was closed, or expired after 10 minutes without a poll (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_listeners/{id}":{"delete":{"operationId":"deleteWebhookListener","tags":["Webhook endpoints"],"summary":"Close a webhook listener","description":"Closes the listener: it receives nothing more, and deliveries it was still holding are dropped. `coss listen` closes its listener when it exits.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The webhook listener's id.","examples":["whlis_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The webhook listener's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The listener was closed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedWebhookListener"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No open webhook listener with this id exists in the API key's environment: it was closed, or expired after 10 minutes without a poll (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook_events/test":{"post":{"operationId":"createTestWebhookEvent","tags":["Webhook endpoints"],"summary":"Send a test event","description":"Sends a sample event of a type to the environment's enabled endpoints subscribed to it and its open listeners (`coss listen`), exactly as a real one is sent: same body, signature, retries and log lines. `coss trigger` calls it. Sandbox environments only. The ids in the sample are made up (pass real ones in `data` for a handler that looks them up), and nothing marks the event as a test: your handler takes it like the real thing. When nothing is subscribed, the event goes nowhere and isn't kept.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestWebhookEventRequest"}}}},"responses":{"200":{"description":"The event that was sent, and to how many receivers.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestEvent"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the `webhook:create` permission, its organization is suspended, or it belongs to a live environment (`sandbox_only`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the type only reaches live environments (`live_only_event_type`: `domain.*`, `account.*`, `billing.*`), or `data` doesn't fit the type (`invalid_test_event`, with `issues`; unknown fields included).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/suppressions":{"post":{"operationId":"createSuppression","tags":["Suppressions"],"summary":"Add an address to the suppression list","description":"Suppresses an address in the API key's environment: later sends skip it, either for every email (`scope: \"*\"`, the default) or only for emails with the given `category` (e.g. to back an unsubscribe link). Adding an address that is already suppressed with the same scope returns the existing entry with status 200.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSuppressionRequest"}}}},"responses":{"200":{"description":"The address already had an entry with this scope.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suppression"}}}},"201":{"description":"The new entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suppression"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`subaccount` names no sub-account of the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSuppressions","tags":["Suppressions"],"summary":"List suppressed addresses","description":"The suppression list of the API key's environment, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"List a sub-account's own list (its id or your uid) instead of the environment's.","examples":["user_8812"]},"required":false,"description":"List a sub-account's own list (its id or your uid) instead of the environment's.","name":"subaccount","in":"query"},{"schema":{"type":"string","description":"Only entries for this address."},"required":false,"description":"Only entries for this address.","name":"address","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","enum":["stream:marketing"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}],"description":"Only entries with this scope."},"required":false,"description":"Only entries with this scope.","name":"scope","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last entry of the previous page."},"required":false,"description":"Cursor: the `id` of the last entry of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of entries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`subaccount` names no sub-account of the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions/check":{"get":{"operationId":"checkSuppression","tags":["Suppressions"],"summary":"Check whether an address is suppressed","description":"Whether a send to `address` (with `category`, if given) would skip it, and the entries that match: those with scope `*` and, with a `category`, those for that category.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The address to check.","examples":["user@example.com"]},"required":true,"description":"The address to check.","name":"address","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The category of the email you plan to send. Without it, only `*` entries count."},"required":false,"description":"The category of the email you plan to send. Without it, only `*` entries count.","name":"category","in":"query"},{"schema":{"type":"string","enum":["transactional","marketing"],"description":"The stream of the email you plan to send (default `transactional`). `marketing` also counts `stream:marketing` entries."},"required":false,"description":"The stream of the email you plan to send (default `transactional`). `marketing` also counts `stream:marketing` entries.","name":"stream","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"The sub-account you plan to send for (its id or your uid): its own entries count too."},"required":false,"description":"The sub-account you plan to send for (its id or your uid): its own entries count too.","name":"subaccount","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The result.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionCheck"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`subaccount` names no sub-account of the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions/import":{"post":{"operationId":"importSuppressions","tags":["Suppressions"],"summary":"Import suppressions in bulk","description":"Adds up to 1000 entries at once, with reason `import`. Each entry is validated on its own: invalid ones are skipped and listed in `invalid`, entries already on the list are left unchanged and counted in `existing`. Importing again is safe.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportSuppressionsRequest"}}}},"responses":{"200":{"description":"What the import did.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionImport"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`subaccount` names no sub-account of the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body is not a list of 1-1000 `{ address, scope? }` objects (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/suppressions/export":{"get":{"operationId":"exportSuppressions","tags":["Suppressions"],"summary":"Export the suppression list as CSV","description":"The whole suppression list of the API key's environment (optionally filtered), oldest first, as CSV with the columns `address,scope,reason,created_at,email_id,id`. The file can be imported again as is. Values a spreadsheet would run as a formula are prefixed with `'`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Export a sub-account's own list (its id or your uid) instead of the environment's.","examples":["user_8812"]},"required":false,"description":"Export a sub-account's own list (its id or your uid) instead of the environment's.","name":"subaccount","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","enum":["stream:marketing"]},{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$"}],"description":"Only entries with this scope."},"required":false,"description":"Only entries with this scope.","name":"scope","in":"query"},{"schema":{"type":"string","enum":["bounce","complaint","manual","import","unsubscribe"],"description":"Only entries with this reason.","examples":["bounce"]},"required":false,"description":"Only entries with this reason.","name":"reason","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The CSV file.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`subaccount` names no sub-account of the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions/{id}":{"get":{"operationId":"getSuppression","tags":["Suppressions"],"summary":"Retrieve a suppression","description":"One entry of the suppression list of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The suppression's id.","examples":["sup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The suppression's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suppression"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No suppression with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSuppression","tags":["Suppressions"],"summary":"Remove a suppression","description":"Removes the entry, so later sends reach the address again (unless another entry still matches). Entries added for bounces and complaints can be removed too.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The suppression's id.","examples":["sup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The suppression's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSuppression"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No suppression with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subaccounts":{"post":{"operationId":"createSubaccount","tags":["Sub-accounts"],"summary":"Create a sub-account","description":"Creates a sub-account: one of your users, who gets their own domains, suppressions, quotas and reputation. Give it a `uid` (e.g. your user's id) to address it by in every path and send. Sub-accounts belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones, a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubaccountRequest"}}}},"responses":{"200":{"description":"The sub-account.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live sub-accounts need a plan with sub-accounts (`plan_feature_unavailable`), up to its limit (`plan_limit_reached`). (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the `uid` is invalid (`invalid_uid`) or taken (`uid_taken`), the quotas don't fit together (`invalid_quotas`), or the sandbox environment has the most sub-accounts it can (100: `too_many_subaccounts`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSubaccounts","tags":["Sub-accounts"],"summary":"List sub-accounts","description":"The environment's sub-accounts, newest first. Sub-accounts belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones, a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"The last `id` of the previous page.","examples":["sub_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":false,"description":"The last `id` of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of sub-accounts.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubaccountList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subaccounts/{subaccount}":{"get":{"operationId":"getSubaccount","tags":["Sub-accounts"],"summary":"Retrieve a sub-account","description":"A sub-account of the API key's environment, by its id or uid, with its quotas and reputation.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","examples":["user_8812"]},"required":true,"description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","name":"subaccount","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The sub-account.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sub-account with this id or uid exists in the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSubaccount","tags":["Sub-accounts"],"summary":"Update a sub-account","description":"Changes the name, uid, metadata, status or quotas. Fields left out keep their value; `status: \"disabled\"` refuses its sends until it is `active` again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","examples":["user_8812"]},"required":true,"description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","name":"subaccount","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubaccountRequest"}}}},"responses":{"200":{"description":"The sub-account.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sub-account with this id or uid exists in the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the uid is invalid (`invalid_uid`) or taken (`uid_taken`), the quotas don't fit together (`invalid_quotas`), or it is being deleted (`subaccount_deleting`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSubaccount","tags":["Sub-accounts"],"summary":"Delete a sub-account","description":"Starts deleting the sub-account: its sends are refused at once, then its domains are released and it is removed with its suppressions (`status` is `deleting` until then). Its emails stay, with its id. Repeating the call returns it as it is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","examples":["user_8812"]},"required":true,"description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","name":"subaccount","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"202":{"description":"The sub-account, being deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sub-account with this id or uid exists in the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subaccounts/{subaccount}/reinstate":{"post":{"operationId":"reinstateSubaccount","tags":["Sub-accounts"],"summary":"Reinstate a sub-account","description":"Lifts the sub-account's reputation pause (or warning) once you fixed what caused it: its rates are measured again from now on. A pause is never lifted on its own. Repeating the call returns it as it is. Your organization's own reputation still counts its sending.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","examples":["user_8812"]},"required":true,"description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","name":"subaccount","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The sub-account.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sub-account with this id or uid exists in the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subaccounts/{subaccount}/stats":{"get":{"operationId":"getSubaccountStats","tags":["Sub-accounts"],"summary":"Retrieve a sub-account's stats","description":"The sub-account's sending per UTC day: recipients, sent, delivered, bounced, complained, failed and suppressed, counted from its emails as they are now (a later bounce moves its day's numbers). Emails are kept 45 days, so earlier days are left out.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","examples":["user_8812"]},"required":true,"description":"The sub-account's `id` (`sub_…`) or your `uid` for it.","name":"subaccount","in":"path"},{"schema":{"type":"string","format":"date","description":"First day (UTC, `YYYY-MM-DD`); default 30 days before `to`.","examples":["2026-10-01"]},"required":false,"description":"First day (UTC, `YYYY-MM-DD`); default 30 days before `to`.","name":"from","in":"query"},{"schema":{"type":"string","format":"date","description":"Last day (UTC, `YYYY-MM-DD`), included; default today.","examples":["2026-10-15"]},"required":false,"description":"Last day (UTC, `YYYY-MM-DD`), included; default today.","name":"to","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The sub-account's stats.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubaccountStats"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No sub-account with this id or uid exists in the API key's environment (`subaccount_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`), or `from` is after `to` (`invalid_range`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms":{"post":{"operationId":"sendSms","tags":["SMS"],"summary":"Send an SMS","description":"Queues a text message from the API key's environment and returns it with `status: \"queued\"`; it is handed to the carrier moments later. Follow it with `GET /v1/sms/{id}` or the `sms.sent`, `sms.delivered`, `sms.undelivered` and `sms.failed` webhooks. Live (`coss_live_…`) keys send `from` one of the organization's numbers whose carrier registration is approved, to the countries the organization allows (US and Canada unless changed in the dashboard). Sandbox (`coss_test_…`) keys accept any `from`, deliver nothing and answer the SMS simulator's numbers (`+15005550006` delivered, `+15005550001` invalid, `+15005550004` filtered by the carrier, `+15005550009` opted out, `+15005550008` replies). A number on the environment's SMS suppression list (it replied STOP, or it can't receive SMS) is skipped: the message is `failed` with `suppressed`. Segments count against the organization's send quota, and each is billed by the destination country.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original message (with its current status) instead of sending again, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original message (with its current status) instead of sending again, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendSmsRequest"}}}},"responses":{"202":{"description":"The message, accepted (`queued` or `scheduled`; `failed` when its number is suppressed). A replay returns the original message with its current status.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sms"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live sending is paused for an overdue invoice or the spend limit (`billing_hold`) or a used-up budget (`budget_exceeded`), the plan doesn't include SMS or the destination country isn't priced (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`insufficient_permissions`), its organization is suspended (`organization_suspended`), or live sending is suspended (`account_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), `to` isn't a valid number (`invalid_phone_number`), `from` isn't one of the organization's numbers (`sender_not_found`) or can't send yet (`sender_not_ready`), the destination country isn't allowed (`country_not_allowed`), or the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or the message's segments exceed the send quota or too many messages went to this number in the last hour (`quota_exceeded`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listSms","tags":["SMS"],"summary":"List SMS","description":"Messages sent from the API key's environment, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Only messages to this number."},"required":false,"description":"Only messages to this number.","name":"to","in":"query"},{"schema":{"type":"string","description":"Only messages in these statuses, comma-separated: `failed`."},"required":false,"description":"Only messages in these statuses, comma-separated: `failed`.","name":"status","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only messages created at or after this time."},"required":false,"description":"Only messages created at or after this time.","name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only messages created before this time."},"required":false,"description":"Only messages created before this time.","name":"created_before","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of messages.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/suppressions":{"post":{"operationId":"createSmsSuppression","tags":["SMS"],"summary":"Add a number to the SMS suppression list","description":"Later sends from the API key's environment to the number are skipped. Adding a number already on the list returns its entry with status 200.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSmsSuppressionRequest"}}}},"responses":{"200":{"description":"The number already had an entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSuppression"}}}},"201":{"description":"The new entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSuppression"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`) or the number isn't valid (`invalid_phone_number`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSmsSuppressions","tags":["SMS"],"summary":"List suppressed numbers","description":"The SMS suppression list of the API key's environment, newest first: opt-outs, invalid numbers and numbers you added.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Only this number's entry."},"required":false,"description":"Only this number's entry.","name":"phone_number","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of entries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSuppressionList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/suppressions/check":{"get":{"operationId":"checkSmsSuppression","tags":["SMS"],"summary":"Check whether a number is suppressed","description":"Whether a phone number is on the SMS suppression list of the API key's environment, with its entry if it is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"required":true,"name":"phone_number","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The result.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSuppressionCheck"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/suppressions/{id}":{"get":{"operationId":"getSmsSuppression","tags":["SMS"],"summary":"Retrieve an SMS suppression","description":"One entry of the SMS suppression list of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The entry's id.","examples":["smssup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The entry's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsSuppression"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No entry with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSmsSuppression","tags":["SMS"],"summary":"Remove a number from the SMS suppression list","description":"Sends to the number go out again. Remove an opt-out only when the person asked to receive messages again (they can also reply START).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The entry's id.","examples":["smssup_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The entry's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSmsSuppression"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No entry with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/received":{"get":{"operationId":"listReceivedSms","tags":["SMS"],"summary":"List received SMS","description":"Messages sent to the organization's numbers whose replies go to the API key's environment, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Only messages from this number."},"required":false,"description":"Only messages from this number.","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"Only messages to this number of yours."},"required":false,"description":"Only messages to this number of yours.","name":"to","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"created_before","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of received messages.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceivedSmsList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/received/{id}":{"get":{"operationId":"getReceivedSms","tags":["SMS"],"summary":"Retrieve a received SMS","description":"One message received on a number of the organization and routed to the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The received message's id.","examples":["smsin_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The received message's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The received message.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceivedSms"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No received message with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/numbers":{"get":{"operationId":"listSmsNumbers","tags":["SMS"],"summary":"List the organization's phone numbers","description":"Every number of the organization, whether it can send live messages now (its carrier registration is approved) and whether its replies arrive in the API key's environment. Numbers are bought and registered in the dashboard.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The numbers.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsNumberList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/sms/{id}":{"get":{"operationId":"getSms","tags":["SMS"],"summary":"Retrieve an SMS","description":"One message sent from the API key's environment, with its current status.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The message's id.","examples":["sms_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The message's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The message.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sms"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No message with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/{id}/events":{"get":{"operationId":"listSmsEvents","tags":["SMS"],"summary":"List an SMS's events","description":"Everything that happened to the message, oldest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The message's id.","examples":["sms_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The message's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The events.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsEventList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No message with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sms/{id}/cancel":{"post":{"operationId":"cancelSms","tags":["SMS"],"summary":"Cancel a scheduled SMS","description":"Cancels a message scheduled with `scheduled_at` before it is sent. Canceling a canceled message returns it as is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The message's id.","examples":["sms_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The message's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The canceled message.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sms"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No message with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The message isn't scheduled (`sms_not_cancelable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/documents":{"post":{"operationId":"uploadSignDocument","tags":["Sign documents"],"summary":"Upload a document","description":"Uploads a PDF (base64, at most 25 MB and 500 pages, not password-protected) for signature requests to use. The response lists each page's size and the text anchors found in it (`{{signature:signer_1}}`), which fields can be placed by. Requests can also take PDFs inline.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSignDocumentRequest"}}}},"responses":{"201":{"description":"The uploaded document.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignDocument"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), or the file isn't a PDF coss.com can read (`invalid_document`: damaged, encrypted or too many pages).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSignDocuments","tags":["Sign documents"],"summary":"List documents","description":"Documents uploaded to the API key's environment, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of documents.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignDocumentList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/documents/{id}":{"get":{"operationId":"getSignDocument","tags":["Sign documents"],"summary":"Retrieve a document","description":"An uploaded document's details: its hash, page sizes and text anchors. Its bytes are never returned here.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The document's id.","examples":["sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The document's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The document.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignDocument"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No document with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSignDocument","tags":["Sign documents"],"summary":"Delete a document","description":"Deletes an uploaded document and its file. Documents a request uses can't be deleted.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The document's id.","examples":["sdoc_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The document's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The document was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSignDocument"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No document with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A signature request uses the document (`document_in_use`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests":{"post":{"operationId":"createSignRequest","tags":["Signature requests"],"summary":"Create a signature request","description":"Asks one or more signers to sign one or more PDFs. Give documents by id (uploaded) or inline, and each signer's fields by position (`page`, `x`, `y`, `width`, `height` in PDF points from the page's top left) or by text anchor (`{{signature:signer_1}}`). Every signer needs a `signature` field. Sent at once unless `send` is `false` (a `draft`). Each signer signs by email (`delivery: \"email\"`, the default) or in your app (`\"embedded\"`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original request (in its current state) instead of creating another, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original request (in its current state) instead of creating another, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignRequestRequest"}}}},"responses":{"201":{"description":"The signature request (`sent`, or `draft`). A replay returns the original request in its current state.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: an overdue invoice or spend limit (`billing_hold`), or the project's budget (`budget_exceeded`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), a document isn't a PDF coss.com can read (`invalid_document`) or isn't in the environment (`not_found`), a field doesn't fit on its page or names an anchor no document has (`invalid_fields`), a signer is listed twice (`invalid_signers`), `expires_at` is out of range (`invalid_expiry`), or the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listSignRequests","tags":["Signature requests"],"summary":"List signature requests","description":"Signature requests of the API key's environment, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Only requests in these statuses, comma-separated: `sent,draft`."},"required":false,"description":"Only requests in these statuses, comma-separated: `sent,draft`.","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of signature requests.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequestList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests/{id}":{"get":{"operationId":"getSignRequest","tags":["Signature requests"],"summary":"Retrieve a signature request","description":"A signature request with its documents, signers and fields, and `signed_document` once it's sealed.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The signature request.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No signature request with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSignRequest","tags":["Signature requests"],"summary":"Delete a signature request","description":"Deletes a request that isn't `sent` (cancel it first) with its signers, fields, audit trail, signatures and signed document, for good. Its documents stay (delete them on their own). Keep the signed document first if you need it: it is your record.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The deleted request.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSignRequest"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No signature request with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is `sent`: cancel it first (`request_not_deletable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests/{id}/send":{"post":{"operationId":"sendSignRequest","tags":["Signature requests"],"summary":"Send a draft signature request","description":"Sends a `draft`. An already sent request is returned as is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The sent request.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: an overdue invoice or spend limit (`billing_hold`), or the project's budget (`budget_exceeded`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No signature request with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request isn't a draft (`request_not_draft`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests/{id}/cancel":{"post":{"operationId":"cancelSignRequest","tags":["Signature requests"],"summary":"Cancel a signature request","description":"Cancels a `draft` or `sent` request: its signers can no longer sign. An already canceled request is returned as is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The canceled request.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No signature request with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is already completed, declined or expired (`request_not_cancelable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests/{id}/audit_trail":{"get":{"operationId":"listSignRequestEvents","tags":["Signature requests"],"summary":"List a signature request's audit trail","description":"Everything that happened to the request, oldest first: who did it, from which address, the documents' SHA-256 when it mattered, and a hash chain (`previous_hash`, `hash`) that shows the trail is complete and unchanged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The audit trail.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignEventList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No signature request with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests/{id}/remind":{"post":{"operationId":"remindSignRequest","tags":["Signature requests"],"summary":"Remind signers","description":"Emails a reminder, with a fresh link, to every email signer of a sent request who hasn't signed and whose turn it is, unless they were emailed in the last hour. Embedded signers are yours to remind. Sent within seconds; each is a `reminded` event in the audit trail.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The request.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No signature request with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request isn't `sent`, or nobody can be reminded now (`reminder_not_due`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests/{id}/signed_document":{"get":{"operationId":"getSignedDocument","tags":["Signature requests"],"summary":"Download the signed document","description":"The completed request's sealed PDF: every document with the signatures and values filled in, then a certificate of completion (signers, how they were identified, what they agreed to, the documents' SHA-256 and the audit trail). coss.com's seal makes any later change visible in PDF viewers. Ready once `signed_document` is set, which the `sign_request.completed` webhook announces.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The sealed PDF.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No signature request with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request isn't completed, or its document is still being sealed (`signed_document_not_ready`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/requests/{id}/signers/{signer_id}/sessions":{"post":{"operationId":"createSignSession","tags":["Signature requests"],"summary":"Create a signing session","description":"A short-lived link to the signing page for one `embedded` signer of a sent request. Your app vouches for who the signer is (the audit trail records `customer_asserted`), so create it only for that signed-in user, when they open the page that shows it. Embed the `url` in an iframe from an origin in your Sign settings' `allowed_origins` (`mountSigning` from `coss/sign` does it), or redirect to it. Each call creates a new session.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The signature request's id.","examples":["sreq_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signature request's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The signer's id (`signers[].id` of the request).","examples":["ssgn_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The signer's id (`signers[].id` of the request).","name":"signer_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignSessionRequest"}}}},"responses":{"201":{"description":"The session, with its link.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignSession"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such signer on a signature request in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The signer signs by email (`signer_not_embedded`), already signed or declined (`signer_finished`), or the request isn't `sent` or has expired (`request_not_signable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/settings":{"get":{"operationId":"getSignSettings","tags":["Sign settings"],"summary":"Get the Sign settings","description":"The API key's environment's settings: which sites may embed the signing page, how it looks, and the consent text signers accept.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"patch":{"operationId":"updateSignSettings","tags":["Sign settings"],"summary":"Update the Sign settings","description":"Changes the fields given; the others keep their values.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSignSettingsRequest"}}}},"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or an origin isn't `https://host[:port]` (`invalid_origin`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/sign/templates":{"post":{"operationId":"createSignTemplate","tags":["Sign templates"],"summary":"Create a template","description":"Documents with fields for roles (`client`, `company`) instead of named signers, made into requests by naming a signer per role. Fields by position or text anchor (resolved now). Can start empty and be built in the embedded builder (create a builder session).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignTemplateRequest"}}}},"responses":{"201":{"description":"The template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignTemplate"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), a document isn't a PDF coss.com can read (`invalid_document`) or isn't in the environment (`not_found`), a field doesn't fit or names an unknown role or anchor (`invalid_fields`), or a role is listed twice (`invalid_signers`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSignTemplates","tags":["Sign templates"],"summary":"List templates","description":"Newest first. Pass the last `id` as `after` while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of templates.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignTemplateList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/templates/{id}":{"get":{"operationId":"getSignTemplate","tags":["Sign templates"],"summary":"Retrieve a template","description":"A template with its documents, roles and fields. `ready` says whether requests can be made from it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id.","examples":["stpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignTemplate"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSignTemplate","tags":["Sign templates"],"summary":"Update a template","description":"Changes the fields given. `documents`, `roles` and `fields` each replace the whole list. Requests already made from it don't change.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id.","examples":["stpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSignTemplateRequest"}}}},"responses":{"200":{"description":"The template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignTemplate"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), a document isn't a PDF coss.com can read (`invalid_document`) or isn't in the environment (`not_found`), a field doesn't fit or names an unknown role or anchor (`invalid_fields`), or a role is listed twice (`invalid_signers`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSignTemplate","tags":["Sign templates"],"summary":"Delete a template","description":"Requests made from it, and its documents, stay.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id.","examples":["stpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The deleted template.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSignTemplate"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/templates/{id}/requests":{"post":{"operationId":"createSignRequestFromTemplate","tags":["Sign templates"],"summary":"Create a request from a template","description":"A signature request with the template's documents and fields: name one signer for each role, and give its merge fields' values. Like creating a request, it is sent at once unless `send` is `false`, and an `Idempotency-Key` makes retries safe.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id.","examples":["stpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original request (in its current state) instead of creating another, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original request (in its current state) instead of creating another, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignRequestFromTemplateRequest"}}}},"responses":{"201":{"description":"The signature request.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing (`request_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The template isn't ready (`template_incomplete`), a role has no signer or two (`invalid_signers`), a merge field doesn't exist (`invalid_fields`), `expires_at` is out of range (`invalid_expiry`), or the `Idempotency-Key` was used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sign/templates/{id}/builder_sessions":{"post":{"operationId":"createSignBuilderSession","tags":["Sign templates"],"summary":"Create a builder session","description":"A short-lived link to the embedded builder for this template: upload documents, add roles, and drag fields onto pages. Embed it with `mountBuilder` from `coss/sign` (from an origin in your Sign settings' `allowed_origins`) for whoever edits the template.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The template's id.","examples":["stpl_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The template's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignBuilderSessionRequest"}}}},"responses":{"201":{"description":"The builder session, with its link.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignBuilderSession"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No template with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sign is temporarily unavailable (`sign_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications":{"post":{"operationId":"startVerification","tags":["Verifications"],"summary":"Start a verification","description":"Sends a one-time code to a phone number (SMS) or an email address and returns the verification, `pending` until you check the code the end user typed (`POST /v1/verifications/check`). Starting again for the same destination while it is pending sends a new code (the earlier one stops working), up to 5 times. Before a new verification costs anything, the fraud guard checks it (your Risk lists, premium-rate numbers, Tor, and velocity per IP, user, number range and country, with how often their codes are entered): a blocked one is stored with its `reasons` and nothing is sent. Pass the end user's `ip` (and your `user_id`) so it can tell them apart. SMS codes come from coss.com's shared numbers unless the environment's Verify settings name one of your own; email codes from your sender, else coss.com's. Sandbox (`coss_test_…`) keys deliver nothing and the code is always zeros.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original verification instead of sending another code, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original verification instead of sending another code, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartVerificationRequest"}}}},"responses":{"201":{"description":"The verification, `pending`, with the send that just went out.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Live sending is paused for an overdue invoice or the spend limit (`billing_hold`) or a used-up budget (`budget_exceeded`), or the plan doesn't include Verify or the destination country isn't priced (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing (`request_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`); `to` isn't a valid number or address (`invalid_destination`) or its country isn't allowed (`country_not_allowed`); the fraud guard blocked it (`verification_blocked`: the verification is stored with its `reasons`); the code was already sent 5 times (`too_many_sends`); the recipient opted out or is suppressed (`recipient_suppressed`); the code couldn't be sent (`send_failed`, `sender_not_ready`…); or the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many codes to this destination or from coss.com's shared numbers today (`quota_exceeded`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"coss.com's shared numbers aren't available for this destination (`shared_sender_unavailable`): name your own number in Verify's settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listVerifications","tags":["Verifications"],"summary":"List verifications","description":"Verifications of the API key's environment, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":320,"description":"Only verifications to this destination."},"required":false,"description":"Only verifications to this destination.","name":"to","in":"query"},{"schema":{"type":"string","enum":["pending","approved","expired","canceled","failed","blocked"],"description":"Only verifications in this status."},"required":false,"description":"Only verifications in this status.","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of verifications.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/check":{"post":{"operationId":"checkVerification","tags":["Verifications"],"summary":"Check a code","description":"Checks the code the end user typed, by the verification's id or by the destination (its latest verification). `valid: true` approves it (`verification.approved`, billed once); a wrong code spends an attempt, and the last one fails it. Checking an approved verification again with its code stays valid until it expires, without being billed again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated check with the same key returns the same answer without spending another attempt. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated check with the same key returns the same answer without spending another attempt. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckVerificationRequest"}}}},"responses":{"200":{"description":"Whether the code is right, and the verification after the check.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationCheck"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such verification in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many checks for this destination (`quota_exceeded`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}":{"get":{"operationId":"getVerification","tags":["Verifications"],"summary":"Retrieve a verification","description":"A verification's status and destination. Its code is never returned.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The verification's id.","examples":["vrf_01k8e2m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The verification's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The verification.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such verification in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/cancel":{"post":{"operationId":"cancelVerification","tags":["Verifications"],"summary":"Cancel a verification","description":"Cancels a pending verification: its code stops working. Canceling it again returns it as is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The verification's id.","examples":["vrf_01k8e2m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The verification's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The canceled verification.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such verification in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The verification isn't pending (`verification_not_cancelable`): approved, failed, blocked or expired.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verify/settings":{"get":{"operationId":"getVerifySettings","tags":["Verify settings"],"summary":"Get the Verify settings","description":"The API key's environment's settings, with defaults filled in: the name codes are sent for, code length, lifetime and attempts, the senders, and the countries SMS codes may go to.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"patch":{"operationId":"updateVerifySettings","tags":["Verify settings"],"summary":"Update the Verify settings","description":"Changes the fields given; the others keep their values. `sms_from` must be one of the organization's numbers, and a live key's `email_from` must be on one of its verified domains.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVerifySettingsRequest"}}}},"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or a sender isn't the organization's (`invalid_settings`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/forms":{"post":{"operationId":"createForm","tags":["Forms"],"summary":"Create a form","description":"A hosted form endpoint: point an HTML `<form action>` (or `coss/forms`) at its `endpoint`. Every submission is screened by Risk (the honeypot, captcha, email, IP, device, velocity and content) and accepted ones go to webhooks (`form.submission.received`), notification emails and contacts. Without `fields`, any field is accepted.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFormRequest"}}}},"responses":{"201":{"description":"The form.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or the form can't be saved: duplicate or misplaced fields (`invalid_fields`), an origin or redirect that isn't https (`invalid_origin`, `invalid_redirect`), a sender or recipient that isn't verified (`invalid_sender`, `invalid_recipient`), an unknown audience, topic or property (`invalid_contacts`), no captcha in the risk settings (`captcha_not_configured`), a hosted page without fields or asking for credentials (`hosted_needs_fields`, `hosted_content_refused`), a blocked file type or uploads turned off while a `file` field remains (`invalid_files`), or too many forms (`form_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Forms isn't available in this deployment yet (`forms_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listForms","tags":["Forms"],"summary":"List forms","description":"The environment's forms, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of forms.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Forms isn't available in this deployment yet (`forms_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}":{"get":{"operationId":"getForm","tags":["Forms"],"summary":"Get a form","description":"A form's settings, with the `endpoint` it posts to and its `hosted_url`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The form.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No form with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Forms isn't available in this deployment yet (`forms_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateForm","tags":["Forms"],"summary":"Update a form","description":"Only the fields given change, within each group (`spam`, `contacts`, …) too.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFormRequest"}}}},"responses":{"200":{"description":"The form.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No form with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Other updates of this form kept racing this one (`form_conflict`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), or the form can't be saved: duplicate or misplaced fields (`invalid_fields`), an origin or redirect that isn't https (`invalid_origin`, `invalid_redirect`), a sender or recipient that isn't verified (`invalid_sender`, `invalid_recipient`), an unknown audience, topic or property (`invalid_contacts`), no captcha in the risk settings (`captcha_not_configured`), a hosted page without fields or asking for credentials (`hosted_needs_fields`, `hosted_content_refused`), a blocked file type or uploads turned off while a `file` field remains (`invalid_files`), or too many forms (`form_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Forms isn't available in this deployment yet (`forms_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteForm","tags":["Forms"],"summary":"Delete a form","description":"Deletes the form with every submission and uploaded file. Its endpoint answers 404 from then on.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The form was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedForm"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No form with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Forms isn't available in this deployment yet (`forms_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}/submissions":{"get":{"operationId":"listFormSubmissions","tags":["Form submissions"],"summary":"List a form's submissions","description":"Newest first. `status` narrows them: `accepted` (delivered), `held` (Risk asked for a review), `spam` and `pending_confirmation` (waiting for the submitter's email link).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"Only submissions in these statuses, comma-separated: `held,spam`."},"required":false,"description":"Only submissions in these statuses, comma-separated: `held,spam`.","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of submissions.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No form with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}/submissions/{submission_id}":{"get":{"operationId":"getFormSubmission","tags":["Form submissions"],"summary":"Get a submission","description":"One submission of the form, with its data, files and Risk's assessment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The submission's id.","examples":["fsub_01kd2m9a0b1c2d3e4f5g6h7j8k"]},"required":true,"description":"The submission's id.","name":"submission_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The submission.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmission"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such form, or no submission with this id in it (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFormSubmission","tags":["Form submissions"],"summary":"Delete a submission","description":"Deletes the submission and its files.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The submission's id.","examples":["fsub_01kd2m9a0b1c2d3e4f5g6h7j8k"]},"required":true,"description":"The submission's id.","name":"submission_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The submission was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedFormSubmission"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such form, or no submission with this id in it (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}/submissions/{submission_id}/release":{"post":{"operationId":"releaseFormSubmission","tags":["Form submissions"],"summary":"Release a submission","description":"Not spam: a `held` or `spam` submission becomes `accepted` and is delivered (webhooks, notifications, contacts), and Risk records its assessment as `legitimate`. Releasing an accepted submission returns it as is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The submission's id.","examples":["fsub_01kd2m9a0b1c2d3e4f5g6h7j8k"]},"required":true,"description":"The submission's id.","name":"submission_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The released submission.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmission"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such form, or no submission with this id in it (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Only held and spam submissions can be released (`submission_not_releasable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forms/{id}/submissions/{submission_id}/files/{file_id}":{"get":{"operationId":"getFormSubmissionFile","tags":["Form submissions"],"summary":"Download a file","description":"A file uploaded with the submission, as `application/octet-stream`: whatever its type, treat it as untrusted (a submitter chose it).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The form's id.","examples":["form_01kd2m8n3p4q5r6s7t8v9w0x1y"]},"required":true,"description":"The form's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The submission's id.","examples":["fsub_01kd2m9a0b1c2d3e4f5g6h7j8k"]},"required":true,"description":"The submission's id.","name":"submission_id","in":"path"},{"schema":{"type":"string","description":"The file's id (`files[].id` of the submission).","examples":["ffile_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The file's id (`files[].id` of the submission).","name":"file_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The file's bytes.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such form, submission or file (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Forms isn't available in this deployment yet (`forms_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts":{"post":{"operationId":"createSchedulingHost","tags":["Scheduling hosts"],"summary":"Create a host","description":"A person who can be booked: one of your users, such as a doctor or a tutor.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHostRequest"}}}},"responses":{"201":{"description":"The host.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHost"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), `time_zone` isn't an IANA name (`invalid_time_zone`), or another host has the `uid` (`uid_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSchedulingHosts","tags":["Scheduling hosts"],"summary":"List hosts","description":"The environment's hosts, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of hosts.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHostList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts/{host}":{"get":{"operationId":"getSchedulingHost","tags":["Scheduling hosts"],"summary":"Retrieve a host","description":"A host by its id or your uid.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The host.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHost"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSchedulingHost","tags":["Scheduling hosts"],"summary":"Update a host","description":"Changes what's given. A `disabled` host keeps its bookings but gets no new ones.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHostRequest"}}}},"responses":{"200":{"description":"The host.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHost"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), `time_zone` isn't an IANA name (`invalid_time_zone`), or another host has the `uid` (`uid_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSchedulingHost","tags":["Scheduling hosts"],"summary":"Delete a host","description":"Removes the host and its schedules and calendars. Refused while bookings are still to come (`host_has_live_bookings`): cancel them, or set the host's status to `disabled`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSchedulingHost"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/reassign":{"post":{"operationId":"reassignSchedulingBooking","tags":["Scheduling bookings"],"summary":"Reassign a booking","description":"Gives a booking to another host, keeping its id and time. Works for every kind: a group session moves as a whole, from any of its seats, and one that's already started changes for the record, with nobody told. Whoever leaves and joins is told, and the attendee unless you say not to.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReassignSchedulingBookingRequest"}}}},"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request doesn't make sense (`invalid_reassignment`), that host can't take it (`reassign_target_unavailable`), nobody can (`no_reassign_candidate`), or the booking can't change (`booking_not_changeable`, `hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/reassign_candidates":{"get":{"operationId":"listSchedulingReassignCandidates","tags":["Scheduling bookings"],"summary":"List who a booking could go to","description":"The environment's other active hosts: members of the event type first, in the order a pool would pick them, each saying whether they're free and why not. Things can change before you ask: reassigning decides again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The host who'd leave, when it could be several."},"required":false,"description":"The host who'd leave, when it could be several.","name":"from_host","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The candidates.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignCandidateList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/reassignments/preview":{"post":{"operationId":"previewSchedulingReassignment","tags":["Scheduling reassignments"],"summary":"Preview a bulk reassignment","description":"Who each booking would go to, and why not when nobody can take it, without moving anything. It works down them in order, so two can't both be promised the same free hour. Change any of it and start the run with `assignments`. Covers the first 500. Things can change before you start it: the run decides again.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewSchedulingReassignmentRequest"}}}},"responses":{"200":{"description":"What would happen.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignmentPreview"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The selection or strategy doesn't make sense (`invalid_reassignment`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/reassignments":{"post":{"operationId":"createSchedulingReassignment","tags":["Scheduling reassignments"],"summary":"Start a bulk reassignment","description":"Moves up to 5,000 bookings in the background, each on its own, so one that can't move never holds up the rest. Nothing's ever cancelled: a booking nobody can take stays where it is, and its item says so. It answers at once: follow the run by its id, or wait for `scheduling.reassignment.completed`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original run instead of starting another, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original run instead of starting another, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSchedulingReassignmentRequest"}}}},"responses":{"202":{"description":"The run, waiting to start.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignment"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this key is still running (`idempotency_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The selection or strategy doesn't make sense, or covers too many bookings (`invalid_reassignment`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listSchedulingReassignments","tags":["Scheduling reassignments"],"summary":"List bulk reassignments","description":"Newest first, with how each is going.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The runs.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignmentList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/reassignments/{id}":{"get":{"operationId":"getSchedulingReassignment","tags":["Scheduling reassignments"],"summary":"Retrieve a bulk reassignment","description":"How it's going.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The reassignment's id."},"required":true,"description":"The reassignment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The run.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignment"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/reassignments/{id}/items":{"get":{"operationId":"listSchedulingReassignmentItems","tags":["Scheduling reassignments"],"summary":"List a bulk reassignment's bookings","description":"Each booking it covers and what happened to it. A group session has one, for one of its seats. Empty until the worker's started on it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The reassignment's id."},"required":true,"description":"The reassignment's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The items.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignmentItemList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/reassignments/{id}/cancel":{"post":{"operationId":"cancelSchedulingReassignment","tags":["Scheduling reassignments"],"summary":"Cancel a bulk reassignment","description":"Stops what hasn't happened yet. What's moved stays moved: undo it for that. Cancelling one that's finished changes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The reassignment's id."},"required":true,"description":"The reassignment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The run.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignment"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/reassignments/{id}/undo":{"post":{"operationId":"undoSchedulingReassignment","tags":["Scheduling reassignments"],"summary":"Undo a bulk reassignment","description":"Gives back what a finished run moved, as a new run. A booking that's moved on since stays where it went, and a former host who's no longer free keeps it from going back, unless you pass `overrides`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The reassignment's id."},"required":true,"description":"The reassignment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndoSchedulingReassignmentRequest"}}}},"responses":{"202":{"description":"The new run.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReassignment"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"It's still running (`reassignment_not_finished`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/holiday_calendars":{"post":{"operationId":"createSchedulingHolidayCalendar","tags":["Scheduling holiday calendars"],"summary":"Create a holiday calendar","description":"Applies a country's public holidays, or your own feed, to some hosts as ordinary out of office entries, kept up to date by coss.com. A host who removes one keeps it removed.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSchedulingHolidayCalendarRequest"}}}},"responses":{"201":{"description":"The calendar.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHolidayCalendar"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"That isn't something to read (`invalid_holiday_calendar`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSchedulingHolidayCalendars","tags":["Scheduling holiday calendars"],"summary":"List holiday calendars","description":"By name. A feed's URL is never shown again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":4096,"description":"The next_cursor from the previous page."},"required":false,"description":"The next_cursor from the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The calendars.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHolidayCalendarList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/holiday_calendars/{id}":{"get":{"operationId":"getSchedulingHolidayCalendar","tags":["Scheduling holiday calendars"],"summary":"Retrieve a holiday calendar","description":"With when it was last read, and why not if it couldn't be.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The holiday calendar's id."},"required":true,"description":"The holiday calendar's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The calendar.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHolidayCalendar"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSchedulingHolidayCalendar","tags":["Scheduling holiday calendars"],"summary":"Update a holiday calendar","description":"Who it applies to, who covers and what happens to bookings. Takes effect shortly.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The holiday calendar's id."},"required":true,"description":"The holiday calendar's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSchedulingHolidayCalendarRequest"}}}},"responses":{"200":{"description":"The calendar.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHolidayCalendar"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSchedulingHolidayCalendar","tags":["Scheduling holiday calendars"],"summary":"Delete a holiday calendar","description":"Hosts can be booked on its days again, shortly: past entries stay.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The holiday calendar's id."},"required":true,"description":"The holiday calendar's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"It's going.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSchedulingHolidayCalendar"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/holiday_calendars/{id}/holidays":{"get":{"operationId":"listSchedulingHolidays","tags":["Scheduling holiday calendars"],"summary":"List a calendar's holidays","description":"What's coming, with names, as last read. Empty until its first read.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The holiday calendar's id."},"required":true,"description":"The holiday calendar's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The holidays.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingHolidayList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/out_of_office":{"post":{"operationId":"createSchedulingOutOfOffice","tags":["Scheduling out of office"],"summary":"Create out of office entries","description":"Marks one host, a list of hosts or everyone matching some attributes as away, for part of a day or for whole dates. They aren't offered during it. Existing bookings stay as they are: list them with the entry's conflicts.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSchedulingOutOfOfficeRequest"}}}},"responses":{"201":{"description":"An entry per host.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOutOfOfficeList"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSchedulingOutOfOffice","tags":["Scheduling out of office"],"summary":"List out of office entries","description":"The environment's entries, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"schema":{"type":"string","description":"One host's entries, by id or uid."},"required":false,"description":"One host's entries, by id or uid.","name":"host","in":"query"},{"schema":{"type":"string","description":"Entries ending after this.","examples":["2027-01-04T15:00:00.000Z"]},"required":false,"description":"Entries ending after this.","name":"start_after","in":"query"},{"schema":{"type":"string","description":"Entries starting before this.","examples":["2027-01-04T15:00:00.000Z"]},"required":false,"description":"Entries starting before this.","name":"start_before","in":"query"},{"schema":{"type":"string","description":"The entries one request made."},"required":false,"description":"The entries one request made.","name":"group","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of entries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOutOfOfficeList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/out_of_office/{id}":{"get":{"operationId":"getSchedulingOutOfOffice","tags":["Scheduling out of office"],"summary":"Retrieve an out of office entry","description":"One entry.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The entry's id.","examples":["ooo_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The entry's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOutOfOffice"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSchedulingOutOfOffice","tags":["Scheduling out of office"],"summary":"Update an out of office entry","description":"Changes what's given. An entry stays with its host.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The entry's id.","examples":["ooo_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The entry's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSchedulingOutOfOfficeRequest"}}}},"responses":{"200":{"description":"The entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOutOfOffice"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSchedulingOutOfOffice","tags":["Scheduling out of office"],"summary":"Delete an out of office entry","description":"The host can be booked in that time again, and any calendar event for it goes.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The entry's id.","examples":["ooo_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The entry's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSchedulingOutOfOffice"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/out_of_office/by_external_id/{external_id}":{"put":{"operationId":"putSchedulingOutOfOffice","tags":["Scheduling out of office"],"summary":"Create or replace an entry by your own id","description":"For syncing from a system of record such as an HR tool: send what it says, as often as you like, and there's one entry for it. Give every field you want to keep.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Your own id for the entry.","examples":["hr_leave_4471"]},"required":true,"description":"Your own id for the entry.","name":"external_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutSchedulingOutOfOfficeRequest"}}}},"responses":{"200":{"description":"The entry, replaced.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOutOfOffice"}}}},"201":{"description":"The entry, new.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOutOfOffice"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/out_of_office/{id}/conflicts":{"get":{"operationId":"listSchedulingOutOfOfficeConflicts","tags":["Scheduling out of office"],"summary":"List an entry's conflicts","description":"Live bookings of the host that fall in the entry, soonest first. Entries never change them.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The entry's id.","examples":["ooo_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The entry's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"required":false,"name":"limit","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The bookings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOutOfOfficeConflictList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts/{host}/schedules":{"post":{"operationId":"createSchedulingSchedule","tags":["Scheduling schedules"],"summary":"Create a schedule","description":"A host's weekly hours and date overrides, in local time. The first one is the host's default.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertScheduleRequest"}}}},"responses":{"201":{"description":"The schedule.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSchedule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), a range ends before it starts or a date has two overrides (`invalid_schedule`), or `time_zone` isn't an IANA name (`invalid_time_zone`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listSchedulingSchedules","tags":["Scheduling schedules"],"summary":"List a host's schedules","description":"All of the host's schedules, oldest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The schedules.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingScheduleList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts/{host}/schedules/{schedule_id}":{"get":{"operationId":"getSchedulingSchedule","tags":["Scheduling schedules"],"summary":"Retrieve a schedule","description":"One of the host's schedules.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"schema":{"type":"string","description":"The schedule's id.","examples":["sched_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The schedule's id.","name":"schedule_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The schedule.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSchedule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateSchedulingSchedule","tags":["Scheduling schedules"],"summary":"Replace a schedule","description":"Replaces its weekly rules, and its overrides when given. Existing bookings stay: a schedule only decides what's offered next.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"schema":{"type":"string","description":"The schedule's id.","examples":["sched_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The schedule's id.","name":"schedule_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertScheduleRequest"}}}},"responses":{"200":{"description":"The schedule.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSchedule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), a range ends before it starts or a date has two overrides (`invalid_schedule`), or `time_zone` isn't an IANA name (`invalid_time_zone`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSchedulingSchedule","tags":["Scheduling schedules"],"summary":"Delete a schedule","description":"Refused for the host's default schedule.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"schema":{"type":"string","description":"The schedule's id.","examples":["sched_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The schedule's id.","name":"schedule_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSchedulingSchedule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"This is the host's default schedule (`invalid_schedule`): make another one the default first.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/event_types":{"post":{"operationId":"createSchedulingEventType","tags":["Scheduling event types"],"summary":"Create an event type","description":"What can be booked: `one_on_one` with one host, `pool` for any free host, `collective` when every required host must be free, or `group` for a session with seats.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEventTypeRequest"}}}},"responses":{"201":{"description":"The event type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingEventType"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), the settings don't fit together (`invalid_event_type`), `grid_time_zone` isn't an IANA name (`invalid_time_zone`), another event type has the `uid` (`uid_taken`), or its text was refused (`content_refused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSchedulingEventTypes","tags":["Scheduling event types"],"summary":"List event types","description":"The environment's event types, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of event types.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingEventTypeList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/event_types/{event_type}":{"get":{"operationId":"getSchedulingEventType","tags":["Scheduling event types"],"summary":"Retrieve an event type","description":"An event type by its id or your uid.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The event type's id or uid.","examples":["evtype_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The event type's id or uid.","name":"event_type","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The event type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingEventType"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSchedulingEventType","tags":["Scheduling event types"],"summary":"Update an event type","description":"Changes what's given. Existing bookings keep what they were booked with. Set `status` to `archived` to stop new bookings.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The event type's id or uid.","examples":["evtype_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The event type's id or uid.","name":"event_type","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEventTypeRequest"}}}},"responses":{"200":{"description":"The event type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingEventType"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), the settings don't fit together (`invalid_event_type`), `grid_time_zone` isn't an IANA name (`invalid_time_zone`), another event type has the `uid` (`uid_taken`), or its text was refused (`content_refused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/event_types/{event_type}/slots":{"get":{"operationId":"listSchedulingSlots","tags":["Scheduling availability"],"summary":"List available slots","description":"Starts an attendee can book between `start` and `end` (at most 62 days), as UTC instants to show in their own time zone. A host whose calendar can't be read isn't offered.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The event type's id or uid.","examples":["evtype_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The event type's id or uid.","name":"event_type","in":"path"},{"schema":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"required":true,"description":"An ISO 8601 instant with an offset.","name":"start","in":"query"},{"schema":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"required":true,"description":"An ISO 8601 instant with an offset.","name":"end","in":"query"},{"schema":{"type":"string","description":"Only this host's slots (id or uid)."},"required":false,"description":"Only this host's slots (id or uid).","name":"host","in":"query"},{"schema":{"type":"integer","minimum":5,"maximum":1440},"required":false,"name":"duration_minutes","in":"query"},{"schema":{"type":"string","description":"A JSON object narrowing a pool, such as `{\"licensed_in\":\"CA\"}`."},"required":false,"description":"A JSON object narrowing a pool, such as `{\"licensed_in\":\"CA\"}`.","name":"attributes","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The slots.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSlotList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or `start`, `end` or `duration_minutes` is invalid: `end` isn't after `start`, the window is longer than 62 days, or the duration isn't one of the event type's (`invalid_time`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/event_types/{event_type}/slots/explain":{"get":{"operationId":"explainSchedulingSlot","tags":["Scheduling availability"],"summary":"Explain a slot","description":"Why one start can or can't be booked right now, host by host, decided the same way a booking is. For support and debugging: it says when a host is busy, so don't show it to attendees.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The event type's id or uid.","examples":["evtype_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The event type's id or uid.","name":"event_type","in":"path"},{"schema":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"required":true,"description":"An ISO 8601 instant with an offset.","name":"start","in":"query"},{"schema":{"type":"string","description":"Only this host (id or uid)."},"required":false,"description":"Only this host (id or uid).","name":"host","in":"query"},{"schema":{"type":"integer","minimum":5,"maximum":1440},"required":false,"name":"duration_minutes","in":"query"},{"schema":{"type":"string","description":"A JSON object narrowing a pool, such as `{\"licensed_in\":\"CA\"}`."},"required":false,"description":"A JSON object narrowing a pool, such as `{\"licensed_in\":\"CA\"}`.","name":"attributes","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Whether it can be booked, and why.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSlotExplanation"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or `start`, `end` or `duration_minutes` is invalid: `end` isn't after `start`, the window is longer than 62 days, or the duration isn't one of the event type's (`invalid_time`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/availability/search":{"post":{"operationId":"searchSchedulingAvailability","tags":["Scheduling availability"],"summary":"Search availability across hosts","description":"For \"who's free\" pages: each matching host's soonest slots, soonest first, across up to 500 hosts.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilitySearchRequest"}}}},"responses":{"200":{"description":"Hosts with slots.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingAvailabilitySearchResult"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or `start`, `end` or `duration_minutes` is invalid: `end` isn't after `start`, the window is longer than 62 days, or the duration isn't one of the event type's (`invalid_time`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/bookings":{"post":{"operationId":"createSchedulingBooking","tags":["Scheduling bookings"],"summary":"Create a booking","description":"Books a slot, or joins a group session. Without a `host`, a pool chooses fairly among those free. An event type that requires approval answers with a `pending_approval` booking.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original booking instead of creating another, for 24 hours. A refused request keeps no key. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original booking instead of creating another, for 24 hours. A refused request keeps no key. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBookingRequest"}}}},"responses":{"201":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: an overdue invoice or spend limit (`billing_hold`), the project's budget (`budget_exceeded`), the plan's allowance (`usage_limit_exceeded`) or what it includes (`plan_feature_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this key is still running (`idempotency_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The time isn't available (`slot_unavailable`), `start`, `duration_minutes` or the occurrence count is out of bounds (`invalid_time`), the attendee's time zone isn't an IANA name (`invalid_time_zone`), the answers or attendee are invalid (`invalid_answers`, `invalid_attendee`), or the `Idempotency-Key` was used with a different request (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listSchedulingBookings","tags":["Scheduling bookings"],"summary":"List bookings","description":"The environment's bookings, newest first. Answers aren't included.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"schema":{"type":"string"},"required":false,"name":"host","in":"query"},{"schema":{"type":"string"},"required":false,"name":"event_type","in":"query"},{"schema":{"type":"string","enum":["held","pending_approval","confirmed","cancelled","declined"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"attendee_uid","in":"query"},{"schema":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"required":false,"description":"An ISO 8601 instant with an offset.","name":"start_after","in":"query"},{"schema":{"type":"string","description":"An ISO 8601 instant with an offset.","examples":["2027-01-04T15:00:00.000Z"]},"required":false,"description":"An ISO 8601 instant with an offset.","name":"start_before","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of bookings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBookingList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}":{"get":{"operationId":"getSchedulingBooking","tags":["Scheduling bookings"],"summary":"Retrieve a booking","description":"A booking with its attendees and their answers.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/reschedule":{"post":{"operationId":"rescheduleSchedulingBooking","tags":["Scheduling bookings"],"summary":"Reschedule a booking","description":"Moves it to a new time, keeping its id. The old time stays booked if the new one isn't free.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescheduleBookingRequest"}}}},"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/cancel":{"post":{"operationId":"cancelSchedulingBooking","tags":["Scheduling bookings"],"summary":"Cancel a booking","description":"Frees the time and removes the calendar event. A cancelled booking stays charged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSchedulingBookingRequest"}}}},"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/events":{"get":{"operationId":"listSchedulingBookingEvents","tags":["Scheduling bookings"],"summary":"List a booking's history","description":"What's happened to a booking, oldest first, and who did it. There's no personal data in here.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The events.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBookingEventList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/approve":{"post":{"operationId":"approveSchedulingBooking","tags":["Scheduling bookings"],"summary":"Approve a booking","description":"Confirms a `pending_approval` booking.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/decline":{"post":{"operationId":"declineSchedulingBooking","tags":["Scheduling bookings"],"summary":"Decline a booking","description":"Refuses a `pending_approval` booking and frees the time.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/notifications":{"get":{"operationId":"listSchedulingBookingNotifications","tags":["Scheduling bookings"],"summary":"List a booking's notifications","description":"What's been queued for this booking and what became of it, newest first, including why something wasn't sent. It never says who it went to.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The last id of the previous page."},"required":false,"description":"The last id of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The notifications.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBookingNotificationList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/no_show":{"post":{"operationId":"markSchedulingBookingNoShow","tags":["Scheduling bookings"],"summary":"Mark a no-show","description":"Records that the attendee didn't come, once the booking has started.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/bookings/{id}/location":{"patch":{"operationId":"updateSchedulingBookingLocation","tags":["Scheduling bookings"],"summary":"Set a booking's location","description":"Where it happens, such as the meeting link you made after the `scheduling.booking.confirmed` webhook.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBookingLocationRequest"}}}},"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/holds":{"post":{"operationId":"createSchedulingHold","tags":["Scheduling bookings"],"summary":"Hold a slot","description":"Keeps a slot for a while (the event type's `hold_ttl_seconds`) so you can take payment, then confirm it. Answers with a `held` booking, which isn't charged and sends nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original booking instead of creating another, for 24 hours. A refused request keeps no key. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original booking instead of creating another, for 24 hours. A refused request keeps no key. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHoldRequest"}}}},"responses":{"201":{"description":"The held booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: an overdue invoice or spend limit (`billing_hold`), the project's budget (`budget_exceeded`), the plan's allowance (`usage_limit_exceeded`) or what it includes (`plan_feature_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this key is still running (`idempotency_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The time isn't available (`slot_unavailable`), `start`, `duration_minutes` or the occurrence count is out of bounds (`invalid_time`), the attendee's time zone isn't an IANA name (`invalid_time_zone`), the answers or attendee are invalid (`invalid_answers`, `invalid_attendee`), or the `Idempotency-Key` was used with a different request (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/holds/{id}/confirm":{"post":{"operationId":"confirmSchedulingHold","tags":["Scheduling bookings"],"summary":"Confirm a hold","description":"Turns a hold into a booking. Always succeeds before the hold expires. Repeating it is safe.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmHoldRequest"}}}},"responses":{"200":{"description":"The booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/holds/{id}":{"delete":{"operationId":"releaseSchedulingHold","tags":["Scheduling bookings"],"summary":"Release a hold","description":"Gives the slot back early.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The cancelled booking.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBooking"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The booking can't change that way (`booking_not_changeable`), the new time isn't available (`slot_unavailable`), or a hold expired (`hold_expired`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/series":{"post":{"operationId":"createSchedulingSeries","tags":["Scheduling series"],"summary":"Create a recurring series","description":"Books up to 52 occurrences, keeping the attendee's local time across DST changes. Each one is an ordinary booking that can move on its own, and a pool keeps one host throughout.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original booking instead of creating another, for 24 hours. A refused request keeps no key. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original booking instead of creating another, for 24 hours. A refused request keeps no key. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSeriesRequest"}}}},"responses":{"201":{"description":"The series and its bookings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSeries"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: an overdue invoice or spend limit (`billing_hold`), the project's budget (`budget_exceeded`), the plan's allowance (`usage_limit_exceeded`) or what it includes (`plan_feature_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this key is still running (`idempotency_in_progress`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The time isn't available (`slot_unavailable`), `start`, `duration_minutes` or the occurrence count is out of bounds (`invalid_time`), the attendee's time zone isn't an IANA name (`invalid_time_zone`), the answers or attendee are invalid (`invalid_answers`, `invalid_attendee`), or the `Idempotency-Key` was used with a different request (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/series/preview":{"post":{"operationId":"previewSchedulingSeries","tags":["Scheduling series"],"summary":"Preview a recurring series","description":"Which occurrences would be free, without booking anything.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSeriesRequest"}}}},"responses":{"200":{"description":"Each occurrence.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSeriesPreview"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or `start`, `end` or `duration_minutes` is invalid: `end` isn't after `start`, the window is longer than 62 days, or the duration isn't one of the event type's (`invalid_time`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/series/{id}/cancel":{"post":{"operationId":"cancelSchedulingSeries","tags":["Scheduling series"],"summary":"Cancel a recurring series","description":"Cancels the occurrences from `from_index` on, or all of them.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The series' id.","examples":["series_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The series' id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSeriesRequest"}}}},"responses":{"200":{"description":"The cancelled bookings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCancelledSeries"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/attendees/{uid}":{"delete":{"operationId":"eraseSchedulingAttendee","tags":["Scheduling bookings"],"summary":"Erase an attendee","description":"Removes this person's details and answers from every booking now, and ends any booker session fixed to them. The bookings themselves stay.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Your id for the attendee.","examples":["patient_77"]},"required":true,"description":"Your id for the attendee.","name":"uid","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"How many were erased.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingAttendeeErasure"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/attendees/erase":{"post":{"operationId":"eraseSchedulingAttendeeByEmail","tags":["Scheduling bookings"],"summary":"Erase an attendee or guest by email","description":"Removes this address's details and answers from every booking now, for someone you have no `uid` for, such as a guest. The bookings themselves stay.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EraseSchedulingAttendeeByEmailRequest"}}}},"responses":{"200":{"description":"How many were erased.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingAttendeeErasureByEmail"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/hosts/{host}/calendar_connections/authorize":{"post":{"operationId":"authorizeSchedulingCalendar","tags":["Scheduling calendars"],"summary":"Start connecting a calendar","description":"A URL for the host to give consent at Google or Microsoft. Open it in a new window: providers refuse to be framed. Coss.com reads only busy times, and writes events with a neutral title unless the event type's `host_calendar_details` is `full`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizeCalendarRequest"}}}},"responses":{"200":{"description":"Where to send the host.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarAuthorization"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or the calendar can't be connected: the provider isn't set up, the server's URL is refused, or a simulated calendar was asked for outside a sandbox environment (`calendar_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts/{host}/calendar_connections":{"post":{"operationId":"createSchedulingCalendarConnection","tags":["Scheduling calendars"],"summary":"Connect a calendar with a password","description":"CalDAV (Apple and others) with an app password, or, in sandbox environments, a `simulated` calendar whose busy times you set yourself. Google and Microsoft use `authorize`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCalendarConnectionRequest"}}}},"responses":{"201":{"description":"The connection.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarConnection"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or the calendar can't be connected: the provider isn't set up, the server's URL is refused, or a simulated calendar was asked for outside a sandbox environment (`calendar_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listSchedulingCalendarConnections","tags":["Scheduling calendars"],"summary":"List a host's calendar connections","description":"With each connection's calendars and which of them count.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The connections.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarConnectionList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts/{host}/calendar_connections/{id}":{"delete":{"operationId":"deleteSchedulingCalendarConnection","tags":["Scheduling calendars"],"summary":"Disconnect a calendar","description":"Revokes coss.com's access and deletes every busy time read through it. One a calendar delegation manages is refused (`calendar_managed`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"schema":{"type":"string","description":"The connection's id.","examples":["calconn_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The connection's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Disconnected.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSchedulingCalendarConnection"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts/{host}/calendars/{calendar_id}":{"patch":{"operationId":"updateSchedulingCalendar","tags":["Scheduling calendars"],"summary":"Choose how a calendar counts","description":"Whether its busy times block slots, and whether bookings are written to it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"schema":{"type":"string","description":"The calendar's id.","examples":["cal_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The calendar's id.","name":"calendar_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCalendarRequest"}}}},"responses":{"200":{"description":"The host's connections.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarConnectionList"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/calendar_delegations":{"post":{"operationId":"createSchedulingCalendarDelegation","tags":["Scheduling calendars"],"summary":"Add a calendar delegation","description":"An admin authorizes once, and every host on the domain gets their calendar with no consent screen. It stays `pending`: authorize what it returns, then verify it. Credentials are never returned.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCalendarDelegationRequest"}}}},"responses":{"201":{"description":"The delegation.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarDelegation"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include calendar delegations (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The credentials or mailbox aren't valid (`invalid_calendar_delegation`), or the provider refused them (`calendar_delegation_refused`, and `message` says what to fix).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSchedulingCalendarDelegations","tags":["Scheduling calendars"],"summary":"List calendar delegations","description":"With how many hosts each has connected.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The delegations.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarDelegationList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/calendar_delegations/{id}":{"get":{"operationId":"getSchedulingCalendarDelegation","tags":["Scheduling calendars"],"summary":"Get a calendar delegation","description":"Its status, what to authorize, and how many hosts it has connected.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The delegation's id.","examples":["caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The delegation's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delegation.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarDelegation"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSchedulingCalendarDelegation","tags":["Scheduling calendars"],"summary":"Update a calendar delegation","description":"New credentials are tried on the verified mailbox before they replace the old ones, and end an outage if they work.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The delegation's id.","examples":["caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The delegation's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCalendarDelegationRequest"}}}},"responses":{"200":{"description":"The delegation.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarDelegation"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include calendar delegations (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The credentials or mailbox aren't valid (`invalid_calendar_delegation`), or the provider refused them (`calendar_delegation_refused`, and `message` says what to fix).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSchedulingCalendarDelegation","tags":["Scheduling calendars"],"summary":"Delete a calendar delegation","description":"Its hosts lose these calendars within minutes. They stay bookable with no conflict check, and events already written stay on their calendars, out of reach of later moves or cancellations.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The delegation's id.","examples":["caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The delegation's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Being removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSchedulingCalendarDelegation"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/calendar_delegations/{id}/verify":{"post":{"operationId":"verifySchedulingCalendarDelegation","tags":["Scheduling calendars"],"summary":"Verify a calendar delegation","description":"Tries one real mailbox. Passing makes it `active`, and its hosts start connecting. Google can take up to 24 hours to apply a new authorization, so a refusal may just need time.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The delegation's id.","examples":["caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The delegation's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCalendarDelegationRequest"}}}},"responses":{"200":{"description":"The delegation.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCalendarDelegation"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include calendar delegations (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The credentials or mailbox aren't valid (`invalid_calendar_delegation`), or the provider refused them (`calendar_delegation_refused`, and `message` says what to fix).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/oauth_apps":{"post":{"operationId":"createSchedulingOauthApp","tags":["Scheduling calendars"],"summary":"Add your own OAuth app","description":"New consents in this environment use it, so the consent screen shows your brand. Connections made before it stay on coss.com's app until their host consents again. On the Scale plan and above. Secrets are never returned.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOauthAppRequest"}}}},"responses":{"201":{"description":"The app.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOauthApp"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The plan doesn't include this (`plan_feature_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The app isn't valid (`invalid_oauth_app`), or the provider refused its client ID and secret (`oauth_app_refused`), and nothing was stored.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listSchedulingOauthApps","tags":["Scheduling calendars"],"summary":"List your OAuth apps","description":"At most one per provider, with how many connections use each.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The apps.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOauthAppList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/oauth_apps/{id}":{"get":{"operationId":"getSchedulingOauthApp","tags":["Scheduling calendars"],"summary":"Get an OAuth app","description":"Its status, what to register at the provider, and how many connections use it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The OAuth app's id.","examples":["calapp_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The OAuth app's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The app.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOauthApp"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSchedulingOauthApp","tags":["Scheduling calendars"],"summary":"Update an OAuth app","description":"A new client secret is tried on a connection before it replaces the old one, and ends an outage if it works. Its client ID can't change: a different app needs its hosts to consent again.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The OAuth app's id.","examples":["calapp_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The OAuth app's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOauthAppRequest"}}}},"responses":{"200":{"description":"The app.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOauthApp"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The app isn't valid (`invalid_oauth_app`), or the provider refused its client ID and secret (`oauth_app_refused`), and nothing was stored.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSchedulingOauthApp","tags":["Scheduling calendars"],"summary":"Delete an OAuth app","description":"Refused while connections use it (`oauth_app_in_use`), since only it can refresh their access: disconnect them first. New consents go back to coss.com's app.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The OAuth app's id.","examples":["calapp_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The OAuth app's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSchedulingOauthApp"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Connections still use it (`oauth_app_in_use`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/hosts/{host}/simulated_busy":{"put":{"operationId":"setSchedulingSimulatedBusy","tags":["Scheduling calendars"],"summary":"Set a simulated calendar's busy times","description":"Sandbox environments only: test how bookings react to a busy calendar.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSimulatedBusyRequest"}}}},"responses":{"204":{"description":"Set.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), or this isn't a sandbox environment: simulated calendars only exist there (`calendar_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/manager_sessions":{"post":{"operationId":"createSchedulingManagerSession","tags":["Scheduling hosts"],"summary":"Create a manager session","description":"Lets a team lead manage cover for the hosts you name, or those matching an attribute filter whenever it's asked: time off, bookings that need someone else, and moving them. It never sees attendees' details. Send the `url` to their browser, or embed it with `coss/scheduling`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSchedulingManagerSessionRequest"}}}},"responses":{"201":{"description":"The session.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSession"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/hosts/{host}/sessions":{"post":{"operationId":"createSchedulingHostSession","tags":["Scheduling hosts"],"summary":"Create a host session","description":"Lets one host manage their own hours, calendars and locations, on coss.com's hosted page or your own UI. Send the `url` to their browser, or embed it with `coss/scheduling`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The host's id or uid.","examples":["host_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The host's id or uid.","name":"host","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSchedulingHostSessionRequest"}}}},"responses":{"201":{"description":"The session.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSession"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/booker_sessions":{"post":{"operationId":"createSchedulingBookerSession","tags":["Scheduling bookings"],"summary":"Create a booker session","description":"Lets a browser book one event type, on coss.com's hosted page or your own UI, without your API key.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSchedulingBookerSessionRequest"}}}},"responses":{"201":{"description":"The session.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSession"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"In live environments: the plan doesn't include this (`plan_feature_unavailable`), or it's past the plan's limit (`plan_limit_reached`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation (`validation_error`, see `issues`), or can't be done: see `code`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/scheduling/bookings/{id}/manage_sessions":{"post":{"operationId":"createSchedulingManageSession","tags":["Scheduling bookings"],"summary":"Create a manage session","description":"Lets an attendee reschedule or cancel this one booking, within the event type's cutoffs. Stops working when the booking's cancelled, or a day after it ends.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The booking's id.","examples":["book_01kd2m9a0b1c2d3e4f5g6h7j8m"]},"required":true,"description":"The booking's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"201":{"description":"The session.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSession"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing with this id or uid exists in the environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/scheduling/settings":{"get":{"operationId":"getSchedulingSettings","tags":["Scheduling settings"],"summary":"Retrieve settings","description":"The environment's scheduling settings.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"patch":{"operationId":"updateSchedulingSettings","tags":["Scheduling settings"],"summary":"Update settings","description":"Changes what's given.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSchedulingSettingsRequest"}}}},"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingSettings"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), the logo isn't a PNG or JPEG it can read (`invalid_logo`), an origin isn't https (`invalid_event_type`), or its text was refused (`content_refused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/tracking_settings":{"get":{"operationId":"getTrackingSettings","tags":["Tracking"],"summary":"Retrieve tracking settings","description":"The environment's open and click tracking default and its category rules. For each of `opens` and `clicks`, a send's own `tracking` wins, then the rule for its `category`, then the default, then off. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's tracking settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/tracking_settings/default":{"patch":{"operationId":"updateTrackingDefault","tags":["Tracking"],"summary":"Update the tracking default","description":"Sets the environment default, which applies to emails without a rule for their category. Fields left out keep their value; if there is no default yet, it is created with them off. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTrackingRuleRequest"}}}},"responses":{"200":{"description":"The environment default.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingRule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"delete":{"operationId":"deleteTrackingDefault","tags":["Tracking"],"summary":"Remove the tracking default","description":"Removes the environment default: emails without a rule for their category are then not tracked unless the send asks. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The default was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedTrackingRule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The environment has no default (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/tracking_settings/categories/{category}":{"patch":{"operationId":"updateTrackingCategory","tags":["Tracking"],"summary":"Update a category's tracking rule","description":"Sets the rule for emails sent with this `category`, which wins over the environment default, e.g. to track `marketing` but never `password-reset`. Fields left out keep their value; a new rule is created with them off. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The category, as sent in `category`.","examples":["password-reset"]},"required":true,"description":"The category, as sent in `category`.","name":"category","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTrackingRuleRequest"}}}},"responses":{"200":{"description":"The category's rule.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingRule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The category or the body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTrackingCategory","tags":["Tracking"],"summary":"Remove a category's tracking rule","description":"Removes the rule: emails of this category follow the environment default again. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the settings that applied when they were sent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,256}$","description":"The category, as sent in `category`.","examples":["password-reset"]},"required":true,"description":"The category, as sent in `category`.","name":"category","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The rule was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedTrackingRule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The environment has no rule for this category (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The category failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/storage_settings":{"get":{"operationId":"getStorageSettings","tags":["Content storage"],"summary":"Retrieve storage settings","description":"Whether coss.com keeps the content of the environment's emails (`content_storage: \"store\"`, the default) or only until each email is sent, fails or is canceled (`\"discard\"`). Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the setting that applied when they were sent.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's storage settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"patch":{"operationId":"updateStorageSettings","tags":["Content storage"],"summary":"Update storage settings","description":"With `content_storage: \"discard\"`, emails sent from now on keep their subject, body, headers, template variables and attachment filenames only until they are sent, fail or are canceled (scheduled emails keep them until their time comes); request logs never keep them. Their metadata (addresses, tags, category, status, recipients, events) is kept as usual. Settings belong to the API key's own environment: a `coss_test_…` key only ever changes sandbox settings. Emails keep the setting that applied when they were sent.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStorageSettingsRequest"}}}},"responses":{"200":{"description":"The environment's storage settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSettings"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/contacts":{"post":{"operationId":"upsertContact","tags":["Contacts"],"summary":"Create or update a contact","description":"Creates the contact with this address in the API key's environment, or updates the existing one: names are replaced when given, `properties` are merged (`null` removes one), `audience_ids` are added and `topics` choices recorded. `status` only changes when passed.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertContactRequest"}}}},"responses":{"200":{"description":"The existing contact, updated.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"201":{"description":"The new contact.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The environment has as many contacts as the organization's plan allows (`plan_limit_reached`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), names an unknown property, audience or topic (`unknown_property`, `audience_not_found`, `topic_not_found`) or a value of the wrong type (`invalid_property`), or sets `status: \"subscribed\"` while double opt-in applies (`double_opt_in_status`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listContacts","tags":["Contacts"],"summary":"List contacts","description":"The contacts of the API key's environment, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Only the contact with this address."},"required":false,"description":"Only the contact with this address.","name":"email","in":"query"},{"schema":{"type":"string","enum":["subscribed","unsubscribed","pending"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"Only members of this audience."},"required":false,"description":"Only members of this audience.","name":"audience_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last contact of the previous page."},"required":false,"description":"Cursor: the `id` of the last contact of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of contacts.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/{id}/confirmation":{"post":{"operationId":"resendContactConfirmation","tags":["Contacts"],"summary":"Resend a contact's confirmation email","description":"Sends a pending contact (double opt-in) its confirmation email again: at most once a day, and three times before it confirms (`status` says what happened).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"What happened.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactConfirmation"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No contact with this id or address exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The marketing settings have no `confirmation_from` (`confirmation_sender_required`), or it isn't on a verified domain of the organization (`domain_not_verified`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/{id}/preference_links":{"post":{"operationId":"createPreferenceLinks","tags":["Contacts"],"summary":"Create a contact's preference links","description":"The contact's preference center and unsubscribe links, for emails you build yourself. They never expire. Marketing email sent through coss.com gets them (and one-click unsubscribe headers) automatically. Needs `contact:update`: whoever has the links can change the contact's consent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePreferenceLinksRequest"}}}},"responses":{"200":{"description":"The links.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferenceLinks"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No contact with this id or address exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/import":{"post":{"operationId":"importContacts","tags":["Contacts"],"summary":"Import contacts in bulk","description":"Creates or updates up to 1000 contacts at once (source `import`). Each entry is validated on its own: invalid ones are skipped and listed in `invalid`. Existing contacts get the new names and properties, but an import never re-subscribes an unsubscribed contact (`kept_unsubscribed`). Imports send no `contact.*` webhooks. Over the plan's contact limit nothing is imported.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportContactsRequest"}}}},"responses":{"200":{"description":"What the import did.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactImport"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The import would exceed the organization's plan's contact limit (`plan_limit_reached`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body is not a list of 1-1000 contacts (`validation_error`), or `audience_id` is unknown (`audience_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/contacts/export":{"get":{"operationId":"exportContacts","tags":["Contacts"],"summary":"Export contacts as CSV","description":"The contacts of the API key's environment (optionally filtered), oldest first, as CSV with the columns `email,first_name,last_name,status`, one column per custom property, then `created_at,id`. The file can be imported again as is. Values a spreadsheet would run as a formula are prefixed with `'`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["subscribed","unsubscribed","pending"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"Only members of this audience."},"required":false,"description":"Only members of this audience.","name":"audience_id","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The CSV file.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/{id}":{"get":{"operationId":"getContact","tags":["Contacts"],"summary":"Retrieve a contact","description":"One contact of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The contact.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No contact with this id or address exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateContact","tags":["Contacts"],"summary":"Update a contact","description":"Changes the fields given; `properties` are merged (`null` removes one).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactRequest"}}}},"responses":{"200":{"description":"The contact.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No contact with this id or address exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), names an unknown property or topic, or a value of the wrong type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteContact","tags":["Contacts"],"summary":"Delete a contact","description":"Deletes the contact with its audience memberships and topic choices. Its suppressions stay: they are about the address, not the contact.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The contact was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedContact"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No contact with this id or address exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts/{id}/topics":{"get":{"operationId":"getContactTopics","tags":["Contacts"],"summary":"Retrieve a contact's topics","description":"Every topic of the environment with the contact's choice and whether its emails reach them.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The topics.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactTopics"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No contact with this id or address exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateContactTopics","tags":["Contacts"],"summary":"Update a contact's topics","description":"Records the contact's choices for the topics given; the others keep theirs.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactTopicsRequest"}}}},"responses":{"200":{"description":"The topics.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactTopics"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No contact with this id or address exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, or names an unknown topic (`topic_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contact_properties":{"get":{"operationId":"listContactProperties","tags":["Contacts"],"summary":"List contact properties","description":"Every custom contact property of the API key's environment (at most 50), by key.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The properties.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPropertyList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"post":{"operationId":"createContactProperty","tags":["Contacts"],"summary":"Create a contact property","description":"Defines a custom property contacts can have. Its key and type can't change; `fallback` is what templates use for contacts without a value.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactPropertyRequest"}}}},"responses":{"201":{"description":"The new property.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactProperty"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, the key exists (`property_exists`), or the environment has 50 properties (`too_many_properties`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/contact_properties/{id}":{"get":{"operationId":"getContactProperty","tags":["Contacts"],"summary":"Retrieve a contact property","description":"One contact property of the API key's environment: its key, type and fallback.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The property's id.","examples":["cprop_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The property's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The property.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactProperty"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No property with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateContactProperty","tags":["Contacts"],"summary":"Update a contact property's fallback","description":"Changes the value used when a contact has none for this property. Its key and type can't change.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The property's id.","examples":["cprop_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The property's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactPropertyRequest"}}}},"responses":{"200":{"description":"The property.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactProperty"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No property with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The fallback doesn't fit the property's type (`invalid_property`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteContactProperty","tags":["Contacts"],"summary":"Delete a contact property","description":"Deletes the property and removes its values from every contact. Refused while a segment filters on it (`property_in_use`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The property's id.","examples":["cprop_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The property's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The property was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedContactProperty"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No property with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A segment filters on the property (`property_in_use`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts":{"get":{"operationId":"listBroadcasts","tags":["Broadcasts"],"summary":"List broadcasts","description":"The API key's environment's broadcasts, newest first, with their stats.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["draft","scheduled","sending","paused","sent","canceled","failed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last broadcast of the previous page."},"required":false,"description":"Cursor: the `id` of the last broadcast of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of broadcasts.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createBroadcast","tags":["Broadcasts"],"summary":"Create a broadcast","description":"Creates a draft, or with `send` or `scheduled_at` a broadcast that starts sending (so it needs `broadcast:send` too). A broadcast goes to every contact of its audience or segment who is subscribed, reached by its topic and not suppressed, as one email each, at the plan's marketing rate.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the broadcast created first instead of creating another, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the broadcast created first instead of creating another, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBroadcastRequest"}}}},"responses":{"201":{"description":"The new broadcast.","headers":{"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing (`request_in_progress`); retry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, the audience, segment or topic doesn't exist (`invalid_target`, `topic_not_found`), its content could render too long (`content_too_large`), the `Idempotency-Key` was used with another body (`idempotency_key_reused`), or it can't start (see `POST …/send`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts/{id}":{"get":{"operationId":"getBroadcast","tags":["Broadcasts"],"summary":"Retrieve a broadcast","description":"One broadcast of the API key's environment, with its status and stats.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The broadcast.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateBroadcast","tags":["Broadcasts"],"summary":"Update a draft broadcast","description":"Changes a draft; fields left out keep their value, `null` clears one.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBroadcastRequest"}}}},"responses":{"200":{"description":"The broadcast.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, the broadcast isn't a draft (`broadcast_not_editable`), or its content could render too long (`content_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteBroadcast","tags":["Broadcasts"],"summary":"Delete a broadcast","description":"Deletes a draft, or a broadcast canceled before any of its emails were made.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The broadcast was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedBroadcast"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The broadcast has sent emails (`broadcast_not_editable`): cancel it instead.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts/{id}/send":{"post":{"operationId":"sendBroadcast","tags":["Broadcasts"],"summary":"Send a broadcast","description":"Starts sending a draft, now or at `scheduled_at`. Sending a broadcast that already started returns it as it is.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendBroadcastRequest"}}}},"responses":{"200":{"description":"The broadcast.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The broadcast can't start: no postal address (`mailing_address_required`), an unverified From domain (`domain_not_verified`), marketing paused (`marketing_paused`), or it already ended (`broadcast_not_sendable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts/{id}/cancel":{"post":{"operationId":"cancelBroadcast","tags":["Broadcasts"],"summary":"Cancel a broadcast","description":"Stops it for good: its emails not yet handed to the provider are dropped (the ones on their way still go). Canceling a canceled broadcast returns it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The broadcast.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The broadcast already ended (`broadcast_not_sendable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts/{id}/pause":{"post":{"operationId":"pauseBroadcast","tags":["Broadcasts"],"summary":"Pause a broadcast","description":"Pauses a scheduled or sending broadcast; emails not yet handed to the provider are dropped and made again when it is resumed.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The broadcast.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The broadcast isn't scheduled or sending (`broadcast_not_sendable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts/{id}/resume":{"post":{"operationId":"resumeBroadcast","tags":["Broadcasts"],"summary":"Resume a broadcast","description":"Resumes a paused broadcast where it stopped.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The broadcast.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The broadcast isn't paused (`broadcast_not_sendable`), or it still can't send (see `POST …/send`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts/{id}/test":{"post":{"operationId":"testBroadcast","tags":["Broadcasts"],"summary":"Send a test of a broadcast","description":"Sends its content to up to 5 addresses as ordinary marketing emails (subject prefixed `[Test]`), filled with `contact`'s values or the fallbacks. They count like any send.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestBroadcastRequest"}}}},"responses":{"200":{"description":"The test emails.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastTest"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, or the emails can't be sent (e.g. `mailing_address_required`, `domain_not_verified`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The API key's send rate limit (`rate_limited`) or the send quota (`quota_exceeded`) is used up.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/broadcasts/{id}/emails":{"get":{"operationId":"listBroadcastEmails","tags":["Broadcasts"],"summary":"List a broadcast's emails","description":"The emails made so far, one per contact, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The broadcast's id.","examples":["bcast_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The broadcast's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last email of the previous page."},"required":false,"description":"Cursor: the `id` of the last email of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of emails.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastEmailList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No broadcast with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audiences":{"get":{"operationId":"listAudiences","tags":["Audiences"],"summary":"List audiences","description":"The static contact lists of the API key's environment, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of audiences.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAudience","tags":["Audiences"],"summary":"Create an audience","description":"Creates a static contact list in the API key's environment. Names are unique within it (`name_taken`). Add its members with `POST /v1/audiences/{id}/contacts`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAudienceRequest"}}}},"responses":{"201":{"description":"The new audience.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Audience"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, or the name is taken (`name_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/audiences/{id}":{"get":{"operationId":"getAudience","tags":["Audiences"],"summary":"Retrieve an audience","description":"One audience of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audience's id.","examples":["aud_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audience's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The audience.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Audience"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No audience with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAudience","tags":["Audiences"],"summary":"Rename an audience","description":"Renames an audience. Its members stay.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audience's id.","examples":["aud_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audience's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAudienceRequest"}}}},"responses":{"200":{"description":"The audience.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Audience"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No audience with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, or the name is taken (`name_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteAudience","tags":["Audiences"],"summary":"Delete an audience","description":"Deletes the audience; its contacts stay. Refused while a segment filters on it (`audience_in_use`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audience's id.","examples":["aud_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audience's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The audience was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedAudience"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No audience with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A segment filters on the audience (`audience_in_use`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audiences/{id}/contacts":{"get":{"operationId":"listAudienceContacts","tags":["Audiences"],"summary":"List an audience's contacts","description":"The audience's members, whatever their status, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audience's id.","examples":["aud_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audience's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of contacts.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No audience with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addAudienceContacts","tags":["Audiences"],"summary":"Add contacts to an audience","description":"Adds existing contacts, by id or address. Members already in it are counted in `existing`; unknown ones are listed in `missing` (create them first).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audience's id.","examples":["aud_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audience's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAudienceContactsRequest"}}}},"responses":{"200":{"description":"What was added.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceContactsAdded"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No audience with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audiences/{id}/contacts/{contact_id}":{"delete":{"operationId":"removeAudienceContact","tags":["Audiences"],"summary":"Remove a contact from an audience","description":"Takes a contact out of the audience. The contact itself stays.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audience's id.","examples":["aud_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audience's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The contact's id, or its address (URL-encoded).","examples":["contact_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The contact's id, or its address (URL-encoded).","name":"contact_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The contact left the audience.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["audience_contact"]},"audience_id":{"type":"string"},"contact_id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","audience_id","contact_id","deleted"]}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The audience doesn't exist, or the contact isn't a member (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/segments":{"get":{"operationId":"listSegments","tags":["Segments"],"summary":"List segments","description":"The segments (contact filters) of the API key's environment, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of segments.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSegment","tags":["Segments"],"summary":"Create a segment","description":"A segment is a filter over the environment's contacts, evaluated whenever it is used, so its contacts are always current.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSegmentRequest"}}}},"responses":{"201":{"description":"The new segment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the filter names an unknown property, audience or topic or uses an operator that doesn't suit the property's type (`invalid_filter`, `param` names the condition), or the name is taken (`name_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/segments/{id}":{"get":{"operationId":"getSegment","tags":["Segments"],"summary":"Retrieve a segment","description":"One segment of the API key's environment, with its filter.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The segment's id.","examples":["seg_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The segment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The segment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No segment with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSegment","tags":["Segments"],"summary":"Update a segment","description":"Changes a segment's name or filter. Only the fields given change.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The segment's id.","examples":["seg_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The segment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSegmentRequest"}}}},"responses":{"200":{"description":"The segment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No segment with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the filter names an unknown property, audience or topic or uses an operator that doesn't suit the property's type (`invalid_filter`, `param` names the condition), or the name is taken (`name_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSegment","tags":["Segments"],"summary":"Delete a segment","description":"Deletes a segment. The contacts it matched stay.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The segment's id.","examples":["seg_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The segment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The segment was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSegment"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No segment with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/segments/{id}/contacts":{"get":{"operationId":"listSegmentContacts","tags":["Segments"],"summary":"List a segment's contacts","description":"The contacts the segment's filter matches now, whatever their status, newest first. A broadcast to the segment goes only to the subscribed ones its topic reaches.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The segment's id.","examples":["seg_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The segment's id.","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of contacts.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No segment with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/topics":{"get":{"operationId":"listTopics","tags":["Topics"],"summary":"List topics","description":"The subscription topics of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of topics.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTopic","tags":["Topics"],"summary":"Create a topic","description":"A topic is what contacts subscribe to, built on categories: emails sent with `category` equal to the topic's `key` are about it, so contacts who opted out (or, for an `opt_out` topic, never opted in) are skipped. Public topics show in the preference center.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTopicRequest"}}}},"responses":{"201":{"description":"The new topic.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Topic"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, the key is taken (`topic_exists`), or the environment has the most topics it can (`too_many_topics`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/topics/{id}":{"get":{"operationId":"getTopic","tags":["Topics"],"summary":"Retrieve a topic","description":"One topic of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The topic's id.","examples":["topic_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The topic's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The topic.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Topic"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No topic with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateTopic","tags":["Topics"],"summary":"Update a topic","description":"Changes the fields given; the key can't change.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The topic's id.","examples":["topic_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The topic's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTopicRequest"}}}},"responses":{"200":{"description":"The topic.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Topic"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No topic with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTopic","tags":["Topics"],"summary":"Delete a topic","description":"Deletes the topic and every contact's choice for it. Refused while a segment filters on it (`topic_in_use`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The topic's id.","examples":["topic_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The topic's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The topic was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedTopic"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No topic with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A segment filters on the topic (`topic_in_use`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketing_settings":{"get":{"operationId":"getMarketingSettings","tags":["Topics"],"summary":"Retrieve the marketing settings","description":"The API key's environment's sender name and the postal address its marketing emails carry.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketingSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"patch":{"operationId":"updateMarketingSettings","tags":["Topics"],"summary":"Update the marketing settings","description":"Changes the fields given (`null` clears one).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMarketingSettingsRequest"}}}},"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketingSettings"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/reputation":{"get":{"operationId":"getReputation","tags":["Reputation"],"summary":"Retrieve the organization's sending reputation","description":"The organization's standing with the coss.com reputation guard and the latest rates it measured over live environments. When a rate reaches its suspension threshold, live sending is suspended automatically (`account_suspended`) until coss.com support reinstates the organization; sandbox keys keep working. Subscribe to the `account.*` webhook events to be notified of changes.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The organization's reputation.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reputation"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/logs":{"get":{"operationId":"listLogs","tags":["Logs"],"summary":"List log lines","description":"The API key's environment log, newest first: every API request made with one of its keys (`source: api`), every email event (`email`) and every webhook delivery attempt (`webhook`). Filter by time range (an hour by default, at most 31 days), source, level, type, status, method, route, key, request, resource or free text. Pass the last `id` as `after` to get the next page while `has_more` is true. Reading logs is not itself logged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of the range (inclusive). Defaults to an hour before `to`."},"required":false,"description":"Start of the range (inclusive). Defaults to an hour before `to`.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the range (exclusive). Defaults to now. At most 31 days."},"required":false,"description":"End of the range (exclusive). Defaults to now. At most 31 days.","name":"to","in":"query"},{"schema":{"type":"string","description":"Only these sources, comma-separated: `api,email,webhook`."},"required":false,"description":"Only these sources, comma-separated: `api,email,webhook`.","name":"source","in":"query"},{"schema":{"type":"string","description":"Only these levels, comma-separated: `warning,error`."},"required":false,"description":"Only these levels, comma-separated: `warning,error`.","name":"level","in":"query"},{"schema":{"type":"string","description":"Only these types, e.g. `email.bounced,email.complained`."},"required":false,"description":"Only these types, e.g. `email.bounced,email.complained`.","name":"type","in":"query"},{"schema":{"type":"string","description":"Only these status codes or classes, e.g. `4xx,503`."},"required":false,"description":"Only these status codes or classes, e.g. `4xx,503`.","name":"status","in":"query"},{"schema":{"type":"string","description":"Only these HTTP methods, e.g. `POST`."},"required":false,"description":"Only these HTTP methods, e.g. `POST`.","name":"method","in":"query"},{"schema":{"type":"string","description":"Only these routes, e.g. `/v1/emails/:id`."},"required":false,"description":"Only these routes, e.g. `/v1/emails/:id`.","name":"route","in":"query"},{"schema":{"type":"string","description":"Only requests made with these API keys."},"required":false,"description":"Only requests made with these API keys.","name":"api_key_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only this request's lines."},"required":false,"description":"Only this request's lines.","name":"request_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only lines about this resource, e.g. an `email_…` id."},"required":false,"description":"Only lines about this resource, e.g. an `email_…` id.","name":"resource_id","in":"query"},{"schema":{"type":"string","maxLength":256,"description":"Free text, matched against the message, path, ids and recipient."},"required":false,"description":"Free text, matched against the message, path, ids and recipient.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last line of the previous page."},"required":false,"description":"Cursor: the `id` of the last line of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of log lines.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`), or the range is empty or longer than 31 days (`invalid_range`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/logs/{id}":{"get":{"operationId":"getLog","tags":["Logs"],"summary":"Retrieve a log line","description":"One line of the API key's environment log.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log line's id.","examples":["log_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log line's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The log line.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Log"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log line with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audit_events":{"get":{"operationId":"listAuditEvents","tags":["Audit log"],"summary":"List audit events","description":"The organization's audit log, newest first: changes made by members in the dashboard, by API keys (from any environment) and by coss.com support. The audit log is organization-wide, so every key of the organization reads the same events. Filter by action (an entry ending in `.` matches a whole resource, e.g. `domain.`), actor, target, environment or time. Pass the last `id` as `after` to get the next page while `has_more` is true. Reading the audit log is not itself logged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Only these actions, comma-separated. An entry ending in `.` matches every action of that resource: `domain.,api_key.created`."},"required":false,"description":"Only these actions, comma-separated. An entry ending in `.` matches every action of that resource: `domain.,api_key.created`.","name":"action","in":"query"},{"schema":{"type":"string","description":"Only these actor types, e.g. `user,api_key`."},"required":false,"description":"Only these actor types, e.g. `user,api_key`.","name":"actor_type","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only changes made by this user or API key."},"required":false,"description":"Only changes made by this user or API key.","name":"actor_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only changes to this resource, e.g. a `dom_…` id."},"required":false,"description":"Only changes to this resource, e.g. a `dom_…` id.","name":"target_id","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only changes in this environment."},"required":false,"description":"Only changes in this environment.","name":"environment_id","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events at or after this time."},"required":false,"description":"Only events at or after this time.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events before this time."},"required":false,"description":"Only events before this time.","name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last event of the previous page."},"required":false,"description":"Cursor: the `id` of the last event of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of audit events.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include the audit log (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audit_events/{id}":{"get":{"operationId":"getAuditEvent","tags":["Audit log"],"summary":"Retrieve an audit event","description":"One event of the organization's audit log.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The audit event's id.","examples":["oaudit_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The audit event's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The audit event.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEvent"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include the audit log (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No audit event with this id exists in the organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing":{"get":{"operationId":"getBilling","tags":["Billing"],"summary":"Retrieve the organization's billing","description":"The organization's plan (and contract), the current billing month's usage and what it would add to the next invoice so far, its standing (`past_due`, billing holds), payment method, and what the plan includes. Organization-wide: every environment's key sees the same. Plan changes are made in the dashboard; subscribe to the `billing.*` webhook events to follow them.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The organization's billing.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/billing/usage":{"get":{"operationId":"listBillingUsage","tags":["Billing"],"summary":"List usage","description":"Billable usage over a range (the current billing month by default), per meter, dimension and bucket (`hour`, `day` or `month`, UTC), oldest first; with `group_by=environment`, per environment too. Only live environments are billed, so only they appear. Usage counts when it becomes billable (an email when the provider accepts it) and is kept for 400 days.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start (inclusive). Defaults to the start of the current billing month."},"required":false,"description":"Start (inclusive). Defaults to the start of the current billing month.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End (exclusive). Defaults to now. At most 400 days after `from` (7 by hour)."},"required":false,"description":"End (exclusive). Defaults to now. At most 400 days after `from` (7 by hour).","name":"to","in":"query"},{"schema":{"type":"string","enum":["hour","day","month"],"description":"Bucket size (UTC). Defaults to `day`."},"required":false,"description":"Bucket size (UTC). Defaults to `day`.","name":"granularity","in":"query"},{"schema":{"type":"string","enum":["environment","project","api_key","user"],"description":"Split each bucket per environment, project, API key or user (the member whose personal key it was)."},"required":false,"description":"Split each bucket per environment, project, API key or user (the member whose personal key it was).","name":"group_by","in":"query"},{"schema":{"type":"string","enum":["email.recipients","email.dedicated_ip","email.attachment_data","email.received","email.received_data","email.inboxes","sms.segments","sms.received_segments","sms.numbers","sms.registrations","sign.completed_requests","risk.phone_checks","risk.assessments","risk.content_checks","verify.verifications","verify.sms","forms.submissions","forms.file_uploads","scheduling.bookings","scheduling.hosts","hooks.messages"],"description":"Only this meter."},"required":false,"description":"Only this meter.","name":"meter","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"Usage, oldest first.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`), or the range is empty or too long (`invalid_range`: at most 400 days, 7 by hour).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/invoices":{"get":{"operationId":"listInvoices","tags":["Billing"],"summary":"List invoices","description":"The organization's invoices, newest first, without their lines. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["open","paid","void","uncollectible"],"description":"Only invoices in this status."},"required":false,"description":"Only invoices in this status.","name":"status","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Continue after this id (the last of the previous page)."},"required":false,"description":"Continue after this id (the last of the previous page).","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many (default 20)."},"required":false,"description":"At most this many (default 20).","name":"limit","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of invoices.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/invoices/{id}":{"get":{"operationId":"getInvoice","tags":["Billing"],"summary":"Retrieve an invoice","description":"One invoice with its lines.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The invoice's id.","examples":["inv_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The invoice's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The invoice.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No invoice with this id exists in the organization (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/credits":{"get":{"operationId":"listCredits","tags":["Billing"],"summary":"List credits","description":"The organization's credits, newest first: each month's plan credit, prepaid commitments and credits from coss.com support (in dollars, or free units of a product), with what's left. Only usable ones by default (`status=all` for every one). Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["active","all"],"description":"`active` (default): usable now or later, with something left; `all`: every credit, newest first."},"required":false,"description":"`active` (default): usable now or later, with something left; `all`: every credit, newest first.","name":"status","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Continue after this id (the last of the previous page)."},"required":false,"description":"Continue after this id (the last of the previous page).","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many (default 20)."},"required":false,"description":"At most this many (default 20).","name":"limit","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of credits.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/log_drains":{"post":{"operationId":"createLogDrain","tags":["Log drains"],"summary":"Create a log drain","description":"Streams the environment's logs to a URL: every line `GET /v1/logs` returns (API requests, email events, webhook attempts) and the environment's audit events, posted as signed batches of up to 500 lines or 1 MB, usually within seconds. `format` picks the body: NDJSON for your own endpoint, or the intake API of Loki (Grafana Cloud), Datadog or an OTLP/HTTP collector, with `auth_header` carrying its key. Log drains belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox drains, and a `coss_live_…` key only production ones. The response carries the signing secret, which is returned only here: store it, and verify every NDJSON batch with it (`verifyLogDrainBatch` in the SDK).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLogDrainRequest"}}}},"responses":{"200":{"description":"The drain and its signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization's plan doesn't include log drains (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the URL is not a usable https:// URL (`invalid_url`), the auth header can't be sent (`invalid_auth_header`), or the environment already has 5 drains (`too_many_log_drains`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listLogDrains","tags":["Log drains"],"summary":"List log drains","description":"Every drain of the API key's environment, oldest first. Log drains belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox drains, and a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's log drains.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/log_drains/{id}":{"get":{"operationId":"getLogDrain","tags":["Log drains"],"summary":"Retrieve a log drain","description":"The drain without its signing secret, which is only returned when created.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The log drain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateLogDrain","tags":["Log drains"],"summary":"Update a log drain","description":"Changes the URL, description, sources, format, auth header or `enabled` flag. Omitted fields keep their current value (`auth_header: null` removes the header), and the signing secret stays the same. A batch being retried goes out as the drain is when it is retried. Disabling a drain drops the lines still waiting for it, and nothing is kept for it while it is disabled; enabling it again (also after coss.com disabled it for failing) sends lines logged from then on.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLogDrainRequest"}}}},"responses":{"200":{"description":"The updated drain.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrain"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Re-enabling the drain needs a plan with log drains (`plan_feature_unavailable`) (`billing_error`). Never retried: it needs a plan change or a payment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the URL is not a usable https:// URL (`invalid_url`), or the auth header can't be sent (`invalid_auth_header`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteLogDrain","tags":["Log drains"],"summary":"Delete a log drain","description":"Removes the drain and its batch log. Lines still waiting for it are dropped. To stop it temporarily, set `enabled` to `false` instead.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The drain was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedLogDrain"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/log_drains/{id}/batches":{"get":{"operationId":"listLogDrainBatches","tags":["Log drains"],"summary":"List a drain's batches","description":"The drain's delivery log, newest first: one batch per request, with every HTTP attempt. A failing batch is retried with backoff for about a day (10 attempts); if every attempt fails, the drain is disabled. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"schema":{"type":"string","enum":["pending","succeeded","failed"],"description":"Only batches with this status."},"required":false,"description":"Only batches with this status.","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last batch of the previous page."},"required":false,"description":"Cursor: the `id` of the last batch of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of batches.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainBatchList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/log_drains/{id}/batches/{batch_id}":{"get":{"operationId":"getLogDrainBatch","tags":["Log drains"],"summary":"Retrieve a batch","description":"One batch of the drain, with every HTTP attempt.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The log drain's id.","examples":["drain_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The log drain's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The batch's id.","examples":["drainbat_01k7c8n2b5d7f9h1k3m5p7r9tv"]},"required":true,"description":"The batch's id.","name":"batch_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The batch.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrainBatch"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No log drain with this id exists in the API key's environment, or the drain has no batch with this id (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/event_types":{"post":{"operationId":"createHookEventType","tags":["Hooks event types"],"summary":"Create an event type","description":"Adds a type to the catalog your applications' users subscribe from (in the portal, or the `filter_types` of an endpoint), with a description, a JSON Schema and examples to show them. Messages can be sent with any type, registered or not. Hooks resources belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones, a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHookEventTypeRequest"}}}},"responses":{"200":{"description":"The event type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEventType"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the type exists (`event_type_exists`), its schema and examples are larger than 64 KB (`payload_too_large`), or the environment has 1000 types (`too_many_event_types`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listHookEventTypes","tags":["Hooks event types"],"summary":"List event types","description":"The environment's event types by name; archived ones only with `include_archived`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false"],"description":"Also list archived types (default `false`)."},"required":false,"description":"Also list archived types (default `false`).","name":"include_archived","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `name` of the last type of the previous page."},"required":false,"description":"Cursor: the `name` of the last type of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of event types.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEventTypeList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/event_types/{name}":{"get":{"operationId":"getHookEventType","tags":["Hooks event types"],"summary":"Retrieve an event type","description":"An event type of the API key's environment, archived or not.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The event type's name.","examples":["invoice.paid"]},"required":true,"description":"The event type's name.","name":"name","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The event type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEventType"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event type with this name exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateHookEventType","tags":["Hooks event types"],"summary":"Update an event type","description":"Changes its description, schema or examples, or archives or restores it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The event type's name.","examples":["invoice.paid"]},"required":true,"description":"The event type's name.","name":"name","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHookEventTypeRequest"}}}},"responses":{"200":{"description":"The event type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEventType"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event type with this name exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, `payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"archiveHookEventType","tags":["Hooks event types"],"summary":"Archive an event type","description":"Hides the type from the portal and from new subscriptions. Endpoints already subscribed keep receiving it. Restore it with `PATCH … { archived: false }`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The event type's name.","examples":["invoice.paid"]},"required":true,"description":"The event type's name.","name":"name","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The archived event type.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEventType"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No event type with this name exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications":{"post":{"operationId":"createHookApplication","tags":["Hooks applications"],"summary":"Create an application","description":"Creates an application: one of your customers (or users), who gets their own endpoints and portal. Give it a `uid` (e.g. your customer's id) to address it by in every path. Hooks resources belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones, a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHookApplicationRequest"}}}},"responses":{"200":{"description":"The application.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookApplication"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the `uid` is taken (`uid_taken`), or the environment has the most applications it can (100,000 live, 100 sandbox: `too_many_applications`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listHookApplications","tags":["Hooks applications"],"summary":"List applications","description":"The environment's applications, newest first. Hooks resources belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones, a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last application of the previous page."},"required":false,"description":"Cursor: the `id` of the last application of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of applications.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookApplicationList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}":{"get":{"operationId":"getHookApplication","tags":["Hooks applications"],"summary":"Retrieve an application","description":"An application of the API key's environment, by its id or uid.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The application.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookApplication"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No application with this id or uid exists in the API key's environment (`application_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateHookApplication","tags":["Hooks applications"],"summary":"Update an application","description":"Changes the name, uid or metadata. Fields left out keep their value.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHookApplicationRequest"}}}},"responses":{"200":{"description":"The application.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookApplication"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No application with this id or uid exists in the API key's environment (`application_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`) or the uid is taken (`uid_taken`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteHookApplication","tags":["Hooks applications"],"summary":"Delete an application","description":"Deletes the application with its endpoints and portal sessions; pending deliveries stop. Its messages are no longer reachable and are deleted with the rest of their day's data.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The application was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedHookApplication"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No application with this id or uid exists in the API key's environment (`application_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints":{"post":{"operationId":"createHookEndpoint","tags":["Hooks endpoints"],"summary":"Create an endpoint","description":"Registers a URL of the application's user that receives its messages, each request signed (Standard Webhooks) with the endpoint's own secret, returned here. Usually your users add endpoints themselves in the portal. Hooks resources belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones, a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHookEndpointRequest"}}}},"responses":{"200":{"description":"The endpoint and its signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpointWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the URL is not a usable https:// URL (`invalid_url`), a filter type is unknown or archived (`unknown_event_type`), the secret is malformed (`invalid_secret`), or the application has the most endpoints it can (50 live, 5 sandbox: `too_many_endpoints`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listHookEndpoints","tags":["Hooks endpoints"],"summary":"List endpoints","description":"The application's endpoints, oldest first. Secrets are never included.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The application's endpoints.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpointList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints/{endpoint_id}":{"get":{"operationId":"getHookEndpoint","tags":["Hooks endpoints"],"summary":"Retrieve an endpoint","description":"An endpoint of the application.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The endpoint.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpoint"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateHookEndpoint","tags":["Hooks endpoints"],"summary":"Update an endpoint","description":"Changes the URL, description, filter types, rate limit, metadata or `enabled`. Enabling it again clears a failure streak. The secret stays the same (see roll secret).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHookEndpointRequest"}}}},"responses":{"200":{"description":"The endpoint.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpoint"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, `invalid_url`, `unknown_event_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteHookEndpoint","tags":["Hooks endpoints"],"summary":"Delete an endpoint","description":"Deletes the endpoint; its pending deliveries fail. Its delivery log stays.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The endpoint was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedHookEndpoint"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints/{endpoint_id}/secret":{"get":{"operationId":"getHookEndpointSecret","tags":["Hooks endpoints"],"summary":"Retrieve an endpoint's secret","description":"The endpoint's current signing secret, e.g. to show its user. Needs `hook:update`, like rolling it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The signing secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpointSecret"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints/{endpoint_id}/roll_secret":{"post":{"operationId":"rollHookEndpointSecret","tags":["Hooks endpoints"],"summary":"Roll an endpoint's secret","description":"Replaces the signing secret, returned here. Until `previous_secret_expires_at`, requests carry a signature with each secret, so the receiver can switch without rejecting any. Not idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RollHookEndpointSecretRequest"}}}},"responses":{"200":{"description":"The endpoint and its new secret.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpointWithSecret"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints/{endpoint_id}/recover":{"post":{"operationId":"recoverHookEndpoint","tags":["Hooks endpoints"],"summary":"Recover failed deliveries","description":"Queues every delivery to the endpoint that failed, of messages sent since `since`, for one more attempt each, e.g. after its receiver was down. coss.com works through them in the background (oldest first); follow `status` with the returned recovery. The endpoint must be enabled.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoverHookEndpointRequest"}}}},"responses":{"200":{"description":"The recovery.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpointRecovery"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`) or the endpoint is disabled (`endpoint_disabled`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints/{endpoint_id}/recoveries/{recovery_id}":{"get":{"operationId":"getHookEndpointRecovery","tags":["Hooks endpoints"],"summary":"Retrieve a recovery","description":"A recovery of the endpoint: `pending` while deliveries are still being requeued.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"schema":{"type":"string","examples":["hrec_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"name":"recovery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The recovery.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookEndpointRecovery"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints/{endpoint_id}/test":{"post":{"operationId":"sendHookEndpointTest","tags":["Hooks endpoints"],"summary":"Send a test message","description":"Sends a message to this endpoint only (whatever its filter), with the given payload or the event type's first example. It counts against the send quota like any message.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendHookTestRequest"}}}},"responses":{"202":{"description":"The test message, queued.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookMessage"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An invoice is overdue or the spend or credit limit was reached (`billing_hold`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, `payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/endpoints/{endpoint_id}/deliveries":{"get":{"operationId":"listHookEndpointDeliveries","tags":["Hooks endpoints"],"summary":"List an endpoint's deliveries","description":"The endpoint's deliveries, newest first.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","description":"The endpoint's id.","examples":["hep_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The endpoint's id.","name":"endpoint_id","in":"path"},{"schema":{"type":"string","enum":["pending","succeeded","failed"],"description":"Only deliveries with this status."},"required":false,"description":"Only deliveries with this status.","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last delivery of the previous page."},"required":false,"description":"Cursor: the `id` of the last delivery of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of deliveries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookDeliveryList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application, or no endpoint with this id in it (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/messages":{"post":{"operationId":"sendHookMessage","tags":["Hooks messages"],"summary":"Send a message","description":"Queues a message to the application: coss.com delivers it to each of its enabled endpoints subscribed to `event_type` within seconds, signed with each endpoint's secret, and retries failures with backoff for about a day. Each request's `webhook-id` header is the message's id. Counts against the send quota once per endpoint it goes to (at least once). A live message is billed once, whatever its fan-out; retries and sandbox are free. Live sends are refused while the organization is suspended (`account_suspended`), on a billing hold (`billing_hold`), over a budget (`budget_exceeded`) or past Free's monthly messages (`usage_limit_exceeded`). Hooks resources belong to the API key's own environment: a `coss_test_…` key only ever sees sandbox ones, a `coss_live_…` key only production ones.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original message instead of sending again, for 24 hours. 1-256 characters.","examples":["invoice-1042-paid"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original message instead of sending again, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendHookMessageRequest"}}}},"responses":{"202":{"description":"The message, queued for delivery.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when the response replays an earlier request with this key.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookMessage"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The plan or the account's billing stands in the way of this live send: Free's monthly messages are used up (`usage_limit_exceeded`), an invoice is overdue or the spend or credit limit was reached (`billing_hold`), or a budget is spent (`budget_exceeded`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No application with this id or uid exists in the API key's environment (`application_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress (`request_in_progress`); retry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the payload is larger than 256 KB (`payload_too_large`), or the Idempotency-Key was used with another body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listHookMessages","tags":["Hooks messages"],"summary":"List messages","description":"The application's messages, newest first (kept for 30 days).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"Only messages of this type."},"required":false,"description":"Only messages of this type.","name":"event_type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last message of the previous page."},"required":false,"description":"Cursor: the `id` of the last message of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of messages.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookMessageList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No application with this id or uid exists in the API key's environment (`application_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/messages/{message_id}":{"get":{"operationId":"getHookMessage","tags":["Hooks messages"],"summary":"Retrieve a message","description":"A message of the application, with its payload.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","examples":["hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"name":"message_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The message.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookMessage"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application or message (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/messages/{message_id}/deliveries":{"get":{"operationId":"listHookMessageDeliveries","tags":["Hooks messages"],"summary":"List a message's deliveries","description":"One delivery per endpoint the message went to.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","examples":["hmsg_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"name":"message_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The message's deliveries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookDeliveryList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application or message (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/deliveries/{delivery_id}":{"get":{"operationId":"getHookDelivery","tags":["Hooks messages"],"summary":"Retrieve a delivery","description":"One message's delivery to one endpoint.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","examples":["hdel_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"name":"delivery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delivery.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookDelivery"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application or delivery (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/deliveries/{delivery_id}/attempts":{"get":{"operationId":"listHookDeliveryAttempts","tags":["Hooks messages"],"summary":"List a delivery's attempts","description":"Every HTTP request of the delivery, oldest first, with response excerpts.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","examples":["hdel_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"name":"delivery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delivery's attempts.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookAttemptList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application or delivery (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/deliveries/{delivery_id}/retry":{"post":{"operationId":"retryHookDelivery","tags":["Hooks messages"],"summary":"Retry a delivery","description":"Queues a finished delivery for one more attempt within seconds, to the endpoint's current URL and secret. A `pending` delivery is returned unchanged.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"schema":{"type":"string","examples":["hdel_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"name":"delivery_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The delivery.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookDelivery"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such application or delivery (`application_not_found`, `not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/applications/{application}/portal_sessions":{"post":{"operationId":"createHookPortalSession","tags":["Hooks portal"],"summary":"Create a portal session","description":"Signs the application's user in to the portal, where they add endpoints, pick event types, see deliveries and retry them, without you building any UI. Create one each time the user opens it (from your backend: never expose the API key) and open or embed the returned `url`; embedding needs the site's origin in the environment's portal settings.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The application's `id` (`happ_…`) or your `uid` for it.","examples":["customer_8812"]},"required":true,"description":"The application's `id` (`happ_…`) or your `uid` for it.","name":"application","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHookPortalSessionRequest"}}}},"responses":{"200":{"description":"The session, with its URL.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookPortalSession"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No application with this id or uid exists in the API key's environment (`application_not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The portal isn't available yet (`portal_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/received_emails":{"get":{"operationId":"listReceivedEmails","tags":["Receiving"],"summary":"List received emails","description":"Emails received by the API key's environment, newest first, without their bodies and headers (retrieve one for those). Pass the last `id` as `after` to get the next page while `has_more` is true. An `email.received` webhook announces each one as it arrives.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last email of the previous page."},"required":false,"description":"Cursor: the `id` of the last email of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of received emails.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceivedEmailList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/received_emails/address":{"get":{"operationId":"getInboundAddress","tags":["Receiving"],"summary":"Retrieve the environment's inbound address","description":"The environment's own domain under coss.com's inbound domain: email sent to any address at it (e.g. `support@<domain>`) is received by this environment, with no DNS setup. To receive at your own domain, add a receiving domain instead.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The environment's inbound address.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundAddress"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"This deployment does not receive email (`receiving_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/received_emails/{id}":{"get":{"operationId":"getReceivedEmail","tags":["Receiving"],"summary":"Retrieve a received email","description":"The received email with its headers, text and HTML bodies (each cut at 2 MB, see `truncated`) and attachment metadata. HTML is the sender's: sanitize it before showing it to anyone.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The received email's id.","examples":["rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The received email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The received email.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceivedEmail"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No received email with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteReceivedEmail","tags":["Receiving"],"summary":"Delete a received email","description":"Deletes the received email with its raw message and attachments right away, instead of at the end of its retention period.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The received email's id.","examples":["rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The received email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The received email was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedReceivedEmail"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No received email with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/received_emails/{id}/raw":{"get":{"operationId":"getReceivedEmailRaw","tags":["Receiving"],"summary":"Download a received email's raw message","description":"The whole message as received (`message/rfc822`), for your own MIME parser or archive.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The received email's id.","examples":["rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The received email's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The raw message.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"message/rfc822":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No received email with this id exists in this environment. Blocked emails (a virus verdict) keep no content (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/received_emails/{id}/attachments/{attachment_id}":{"get":{"operationId":"getReceivedEmailAttachment","tags":["Receiving"],"summary":"Download an attachment of a received email","description":"The attachment's bytes, always as `application/octet-stream` (its declared type is the attachment's `content_type`): treat them as untrusted.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The received email's id.","examples":["rcvd_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The received email's id.","name":"id","in":"path"},{"schema":{"type":"string","description":"The attachment's id (from the received email's `attachments`).","examples":["rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8"]},"required":true,"description":"The attachment's id (from the received email's `attachments`).","name":"attachment_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The attachment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such received email or attachment in this environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes":{"post":{"operationId":"createInbox","tags":["Inboxes"],"summary":"Create an inbox","description":"Gives an agent (or anyone) its own email address in the API key's environment: `username@<the environment's inbound domain>`, which needs no DNS setup, or an address at one of the environment's receiving domains (`domain`). Mail to it is kept as threads, and each message that arrives sends an `inbox.message.received` webhook. With a `client_id` that already has an inbox, that inbox is returned (200) instead of a new one.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInboxRequest"}}}},"responses":{"200":{"description":"The environment's inbox with this `client_id`.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}},"201":{"description":"The new inbox.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The organization has its plan's maximum of inboxes (`plan_limit_reached`), or the Free plan's included inbox-days are used up this month (`usage_limit_exceeded`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`), the address can't be used (`invalid_address`) or is already an inbox (`address_taken`), `domain` is not a receiving domain of the environment (`unknown_domain`), or the deployment doesn't receive email at coss.com's inbound domain (`receiving_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listInboxes","tags":["Inboxes"],"summary":"List inboxes","description":"The environment's inboxes, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of inboxes.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes/{inbox_id}":{"get":{"operationId":"getInbox","tags":["Inboxes"],"summary":"Retrieve an inbox","description":"One inbox of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The inbox.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No inbox with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateInbox","tags":["Inboxes"],"summary":"Update an inbox","description":"Changes the name messages from the inbox are sent with. Its address never changes.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInboxRequest"}}}},"responses":{"200":{"description":"The updated inbox.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No inbox with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteInbox","tags":["Inboxes"],"summary":"Delete an inbox","description":"Deletes the inbox and its threads. The received emails and emails they held stay in the environment until their retention ends, and mail to the address is still received by the environment (without a thread or `inbox.message.received` webhook).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The inbox was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedInbox"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No inbox with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes/{inbox_id}/threads":{"get":{"operationId":"listInboxThreads","tags":["Inboxes"],"summary":"List an inbox's threads","description":"The inbox's conversations, the one with the latest message first, with a preview of that message. A thread whose `last_inbound_at` equals its `last_message_at` awaits a reply. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of threads.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxThreadList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No inbox with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes/{inbox_id}/threads/{thread_id}":{"get":{"operationId":"getInboxThread","tags":["Inboxes"],"summary":"Retrieve a thread","description":"The conversation with its latest messages, oldest first, each with its text and `extracted_text` (its own words, without the quoted conversation): what an agent reads before it replies. HTML is the sender's: sanitize it before showing it to anyone.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"The thread's id.","examples":["thread_01k7c8m4r0c2b8w9y3d5f6g7h8"]},"required":true,"description":"The thread's id.","name":"thread_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The thread.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxThread"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such inbox or thread in this environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteInboxThread","tags":["Inboxes"],"summary":"Delete a thread","description":"Removes the conversation from the inbox. Its received emails and emails stay in the environment until their retention ends; a later reply starts a new thread.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"The thread's id.","examples":["thread_01k7c8m4r0c2b8w9y3d5f6g7h8"]},"required":true,"description":"The thread's id.","name":"thread_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The thread was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedInboxThread"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such inbox or thread in this environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes/{inbox_id}/messages":{"get":{"operationId":"listInboxMessages","tags":["Inboxes"],"summary":"List an inbox's messages","description":"Messages of every thread, newest first, with a preview instead of their bodies (retrieve one for those). Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 20."},"required":false,"description":"1-100, default 20.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Cursor: the `id` of the last item of the previous page."},"required":false,"description":"Cursor: the `id` of the last item of the previous page.","name":"after","in":"query"},{"schema":{"type":"string","enum":["inbound","outbound"],"description":"Only inbound (received) or outbound (sent) messages."},"required":false,"description":"Only inbound (received) or outbound (sent) messages.","name":"direction","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of messages.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessageList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No inbox with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"sendInboxMessage","tags":["Inboxes"],"summary":"Send a message from an inbox","description":"Starts a thread with a message from the inbox's address, sent like any email (its `email_id` has its delivery events and webhooks; never tracked). Replies to it arrive in the same thread. Live inboxes send only from receiving domains under one of the organization's verified domains (`can_send`); sandbox ones always can, and deliver nothing. Recipients count against the send quota.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes the send safe to retry: a repeat with the same key and body returns the first message instead of sending again (keys are per inbox). 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes the send safe to retry: a repeat with the same key and body returns the first message instead of sending again (keys are per inbox). 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInboxMessageRequest"}}}},"responses":{"202":{"description":"The message, queued for delivery. A replay returns the first one.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessage"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`insufficient_permissions`), its organization is suspended (`organization_suspended`), live sending is suspended (`account_suspended`), or sending is paused for the organization (`sending_paused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No inbox with this id exists in this environment. (`not_found`)","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, `invalid_message`), the inbox can't send (`inbox_cannot_send`), its domain is not verified for sending (`domain_not_verified`), or the `Idempotency-Key` was used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or the message's recipients exceed the send quota (`quota_exceeded`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}":{"get":{"operationId":"getInboxMessage","tags":["Inboxes"],"summary":"Retrieve a message","description":"The message with its text, HTML and `extracted_text`. An outbound message's delivery is its email's (`email_id`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"The message's id.","examples":["imsg_01k7c8m4s1d3c9x0z4e6g7h8j9"]},"required":true,"description":"The message's id.","name":"message_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The message.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessage"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such inbox or message in this environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}":{"get":{"operationId":"getInboxMessageAttachment","tags":["Inboxes"],"summary":"Download an attachment of a message","description":"An inbound message's attachment, always as `application/octet-stream` (its declared type is the attachment's `content_type`): treat it as untrusted.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"The message's id.","examples":["imsg_01k7c8m4s1d3c9x0z4e6g7h8j9"]},"required":true,"description":"The message's id.","name":"message_id","in":"path"},{"schema":{"type":"string","description":"The attachment's id (from the message's `attachments`).","examples":["rcvdatt_01k7c8m4r0c2b8w9y3d5f6g7h8"]},"required":true,"description":"The attachment's id (from the message's `attachments`).","name":"attachment_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The attachment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such inbox, message or attachment in this environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}/reply":{"post":{"operationId":"replyToInboxMessage","tags":["Inboxes"],"summary":"Reply to a message","description":"Replies in the message's thread from the inbox's address: to its sender (its `Reply-To` first), or to an outbound message's recipients again for a follow-up; `reply_all` adds everyone else on it. The subject gets `Re:`, and `In-Reply-To`/`References` let the recipient's mail client thread it. Sent like any email, counted against the send quota.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The inbox's id.","examples":["inbox_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The inbox's id.","name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"The message's id.","examples":["imsg_01k7c8m4s1d3c9x0z4e6g7h8j9"]},"required":true,"description":"The message's id.","name":"message_id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes the send safe to retry: a repeat with the same key and body returns the first message instead of sending again (keys are per inbox). 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes the send safe to retry: a repeat with the same key and body returns the first message instead of sending again (keys are per inbox). 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyInboxMessageRequest"}}}},"responses":{"202":{"description":"The reply, queued for delivery. A replay returns the first one.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessage"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`insufficient_permissions`), its organization is suspended (`organization_suspended`), live sending is suspended (`account_suspended`), or sending is paused for the organization (`sending_paused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such inbox or message in this environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 40 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, `invalid_message`), the inbox can't send (`inbox_cannot_send`), the message has no address to reply to (`no_reply_recipient`), its domain is not verified for sending (`domain_not_verified`), or the `Idempotency-Key` was used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or the message's recipients exceed the send quota (`quota_exceeded`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/assessments":{"post":{"operationId":"createRiskAssessment","tags":["Risk"],"summary":"Assess an event","description":"Assesses a sign-up, login or other event in the API key's environment and returns a decision (`allow`, `review` or `block`) with a score and the reasons behind it. coss.com combines email and IP signals with what it has seen in this environment (velocity, accounts sharing a mailbox, identifiers you reported) and your allow and block lists. Signals that are unavailable at the moment are skipped and listed in `degraded`. Call it from your server, never from the browser, and treat errors as `allow` (fail open) so an outage never locks your users out. `review` decisions also fire a `risk.assessment.review` webhook. Live assessments are billed (`risk.assessments`; plans include some every month) unless they end in `block`. Past Free's allowance, on a billing hold or over a budget, they are free and made without velocity, memory or content (`usage_limit` in `degraded`); they never fail over billing. Sandbox (`coss_test_…`) keys accept documented test addresses (`192.0.2.x`, `@disposable.test`, `@undeliverable.test`).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated request with the same key and body returns the original assessment instead of assessing (and counting) the event again, for 24 hours. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated request with the same key and body returns the original assessment instead of assessing (and counting) the event again, for 24 hours. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskAssessmentRequest"}}}},"responses":{"201":{"description":"The assessment. A replay returns the original assessment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Idempotent-Replayed":{"description":"`true` when this response replays an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessment"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Requests with this `Idempotency-Key` are racing for an expired key (`request_in_progress`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), or the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listRiskAssessments","tags":["Risk"],"summary":"List assessments","description":"The assessments of the API key's environment, newest first. `review_status=open` is the review queue. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/RiskEvent"},"required":false,"description":"What is being assessed. `custom` events are named by `event_name`; velocity is counted per event.","name":"event","in":"query"},{"schema":{"$ref":"#/components/schemas/RiskDecision"},"required":false,"description":"`allow`: go ahead. `review`: suspicious; let it through with limits, or hold it for a person. `block`: refuse it.","name":"decision","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Only assessments of this user."},"required":false,"description":"Only assessments of this user.","name":"user_id","in":"query"},{"schema":{"type":"string","enum":["open","resolved"],"description":"`open`: the review queue."},"required":false,"description":"`open`: the review queue.","name":"review_status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last entry of the previous page."},"required":false,"description":"Cursor: the `id` of the last entry of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of assessments.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/assessments/{id}":{"get":{"operationId":"getRiskAssessment","tags":["Risk"],"summary":"Retrieve an assessment","description":"The email address and IP address are removed 90 days after the assessment; the decision, reasons and signals stay for a year.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The assessment's id.","examples":["rsk_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The assessment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The assessment.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessment"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No assessment with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/assessments/{id}/feedback":{"post":{"operationId":"createRiskFeedback","tags":["Risk"],"summary":"Report an assessment's outcome","description":"Tells coss.com what the assessed user turned out to be. `fraud` and `abuse` make later assessments with the same mailbox, user, IP address or subnet flag it (`history.fraud_*`); `legitimate` takes back what this assessment reported. Resolves an open review. Sending the latest outcome again changes nothing.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The assessment's id.","examples":["rsk_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The assessment's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskFeedbackRequest"}}}},"responses":{"200":{"description":"The assessment with its new outcome.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessment"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No assessment with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/list_entries":{"post":{"operationId":"createRiskListEntry","tags":["Risk"],"summary":"Add an allow or block list entry","description":"Adds an email address (matched by mailbox), domain (with its subdomains), IP address or CIDR range, AS number, country or user id to the environment's allow or block list. An allow-list match makes the decision `allow` whatever else fired; a block-list match makes it `block`. Adding an entry that already exists returns it with status 200.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskListEntryRequest"}}}},"responses":{"200":{"description":"The entry already existed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskListEntry"}}}},"201":{"description":"The new entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskListEntry"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`) or `value` is not a valid value of its `type` (`invalid_list_value`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listRiskListEntries","tags":["Risk"],"summary":"List allow and block list entries","description":"The environment's list entries, newest first. Pass the last `id` as `after` to get the next page while `has_more` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/RiskList"},"required":false,"description":"Which list: `allow` or `block`.","name":"list","in":"query"},{"schema":{"$ref":"#/components/schemas/RiskListEntryType"},"required":false,"description":"`email` (matched by mailbox, dots and `+tags` folded), `domain` (subdomains included), `ip` (an address or CIDR range), `asn`, `country` (ISO 3166-1 alpha-2), `user` (your user id).","name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"1-100, default 50."},"required":false,"description":"1-100, default 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: the `id` of the last entry of the previous page."},"required":false,"description":"Cursor: the `id` of the last entry of the previous page.","name":"after","in":"query"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"A page of entries.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskListEntryList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/list_entries/{id}":{"get":{"operationId":"getRiskListEntry","tags":["Risk"],"summary":"Retrieve a list entry","description":"One allow or block list entry of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The list entry's id.","examples":["rskle_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The list entry's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskListEntry"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No list entry with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteRiskListEntry","tags":["Risk"],"summary":"Remove a list entry","description":"Removes an entry from its list. Later assessments no longer see it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The list entry's id.","examples":["rskle_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The list entry's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The entry was removed.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedRiskListEntry"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No list entry with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/users/{user_id}":{"delete":{"operationId":"forgetRiskUser","tags":["Risk"],"summary":"Forget a user","description":"Call this when you delete one of your users: coss.com deletes what identifies them in the environment (their mailbox, fraud reports, and the user id, email address, IP address and user agent on their assessments). Decisions and reasons stay. Forgetting a user coss.com doesn't know succeeds too.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Your id for the user.","examples":["u_42"]},"required":true,"description":"Your id for the user.","name":"user_id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The user is forgotten.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgottenRiskUser"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/settings":{"get":{"operationId":"getRiskSettings","tags":["Risk"],"summary":"Retrieve the risk settings","description":"The API key's environment's decision thresholds, disabled reasons and captcha provider (never its secret).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The settings.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskSettings"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"patch":{"operationId":"updateRiskSettings","tags":["Risk"],"summary":"Update the risk settings","description":"Changes the fields given. `review_threshold` must not exceed `block_threshold`. Disabled reasons never fire (rules still see the facts behind them). Setting a captcha provider makes assessments verify their `captcha.token` with it; `required` adds `captcha.missing` to assessments without one. `reason_weights` replaces reasons' default weights (for example with calibration's `suggested_weight`); `null` restores a default.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRiskSettingsRequest"}}}},"responses":{"200":{"description":"The settings, updated.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskSettings"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), the thresholds are out of order, or a new captcha provider has no secret (`invalid_settings`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/calibration":{"get":{"operationId":"getRiskCalibration","tags":["Risk"],"summary":"Retrieve the calibration","description":"How often each reason and rule was right over the last 90 days, by the outcomes you reported with feedback, and the reason weights that supports. Nothing changes until you apply them with `reason_weights` in the settings.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The calibration.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskCalibration"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/rules":{"post":{"operationId":"createRiskRule","tags":["Risk"],"summary":"Create a rule","description":"Rules decide after the allow and block lists and before the score thresholds: the first enabled rule (lowest `position`, then oldest) whose conditions match the event sets the decision to its `action`. Conditions test the fields listed in the docs; a field without a value (no IP, no email) never matches. At most 50 rules per environment.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskRuleRequest"}}}},"responses":{"201":{"description":"The new rule.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`) or the environment already has 50 rules (`too_many_rules`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listRiskRules","tags":["Risk"],"summary":"List rules","description":"Every rule of the API key's environment, in evaluation order.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The rules.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRuleList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/rules/{id}":{"get":{"operationId":"getRiskRule","tags":["Risk"],"summary":"Retrieve a rule","description":"One rule of the API key's environment.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The rule's id.","examples":["rskrule_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The rule's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The rule.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No rule with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateRiskRule","tags":["Risk"],"summary":"Update a rule","description":"Changes the fields given; `conditions` replaces the whole list.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The rule's id.","examples":["rskrule_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The rule's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRiskRuleRequest"}}}},"responses":{"200":{"description":"The rule, updated.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRule"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No rule with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteRiskRule","tags":["Risk"],"summary":"Delete a rule","description":"Deletes a rule. Later assessments no longer apply it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The rule's id.","examples":["rskrule_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The rule's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The rule was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedRiskRule"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No rule with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/email/check":{"post":{"operationId":"checkRiskEmail","tags":["Risk"],"summary":"Check an email address","description":"Email intelligence on its own: syntax, disposable domains, whether the domain can receive mail (DNS), role accounts, free providers, the canonical mailbox, typo suggestions and the domain's age (RDAP). Stateless: nothing is stored or counted, so it never flags an address for having been seen before (assessments do). Failed lookups are listed in `degraded`. Sandbox keys see the documented test domains (`@disposable.test`, `@undeliverable.test`, `@new.test`).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskEmailCheckRequest"}}}},"responses":{"200":{"description":"What coss.com knows about the address.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskEmailCheck"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/ip/check":{"post":{"operationId":"checkRiskIp","tags":["Risk"],"summary":"Check an IP address","description":"IP intelligence on its own: Tor exit nodes, cloud and hosting networks, networks mostly used by VPN and proxy services, the network (ASN) and its country. Stateless. Missing IP data is reported in `degraded`. Sandbox keys see the documentation addresses (`192.0.2.1` Tor, `.2` cloud, `.3` VPN, the rest residential).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskIpCheckRequest"}}}},"responses":{"200":{"description":"What coss.com knows about the address.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskIpCheck"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/phone/check":{"post":{"operationId":"checkRiskPhone","tags":["Risk"],"summary":"Check a phone number","description":"Phone intelligence on its own: whether the number exists in its country's numbering plan, its line type (mobile, landline, fixed or non-fixed VoIP, toll-free…) and carrier, and the last SIM swap where carriers share it. Stateless. A failed lookup is reported in `degraded`. Each live check that gets an answer is billed (`risk.phone_checks`; plans include some every month, and Free stops at its allowance); invalid numbers, failed lookups and sandbox checks are free. Limited per organization as well as per key. Sandbox keys see the fictional numbers `+1 202 555 01xx` (`0101` landline, `0102` non-fixed VoIP, `0103` fixed VoIP, `0104` a recent SIM swap, `0199` invalid, the rest mobile).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskPhoneCheckRequest"}}}},"responses":{"200":{"description":"What coss.com knows about the number.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskPhoneCheck"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The plan's included phone checks are used up (`usage_limit_exceeded`), or live checks are paused by an overdue invoice or a spend limit (`billing_hold`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), too many phone checks for this organization (`phone_check_rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Phone checks aren't available at the moment (`phone_lookup_unavailable`), or the API key could not be verified right now (`service_unavailable`). Retry later.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/content/classify":{"post":{"operationId":"classifyRiskContent","tags":["Risk"],"summary":"Classify content","description":"Scores text people post on your platform (a profile bio, a comment, a listing) for spam, phishing, malware and fraud with an AI model, with zero data retention. Returns scores only: you decide what they mean. Neither the text nor the scores are stored, and request logs keep no body for this endpoint. Takes up to 3 seconds; a failure is a 503 you can retry or treat as unknown. Each live classification the model answered is billed (`risk.content_checks`; plans include some every month, and Free stops at its allowance). Limited per organization as well as per key. Sandbox keys use markers instead of a model: `[coss-test:phishing]` scores 0.99, `[coss-test:spam:0.4]` exactly 0.4, everything else 0.01.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskContentClassifyRequest"}}}},"responses":{"200":{"description":"The scores.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskContentClassification"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The plan's included content checks are used up (`usage_limit_exceeded`), or live checks are paused by an overdue invoice, a spend limit (`billing_hold`) or a budget (`budget_exceeded`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), too many classifications for this organization (`classification_rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model failed or took longer than 3 seconds (`classification_unavailable`), or the API key could not be verified right now (`service_unavailable`). Retry later, or go without the scores.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/limits":{"post":{"operationId":"checkRiskLimit","tags":["Risk"],"summary":"Check a rate limit","description":"Takes `cost` tokens (default 1) from `key`'s share of one of your buckets and says whether to let the request through: a 200 either way, with `allowed`. Denied requests take nothing. Each key has its own bucket of `burst` tokens refilling at `limit` per `period_seconds` (GCRA, the algorithm coss.com limits its own API with). coss.com keeps only a keyed hash of `key`. While coss.com can't count, the bucket's `on_failure` answers and `degraded` is true.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Makes retries safe: a repeated allowed check with the same key is answered again without taking more tokens, for an hour. 1-256 characters.","examples":["welcome-user-123"]},"required":false,"description":"Makes retries safe: a repeated allowed check with the same key is answered again without taking more tokens, for an hour. 1-256 characters.","name":"Idempotency-Key","in":"header"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRiskLimitRequest"}}}},"responses":{"200":{"description":"The answer for this request.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskLimit"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`) or the `Idempotency-Key` header is invalid (`invalid_idempotency_key`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this name exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/risk/limit_buckets":{"post":{"operationId":"createRiskLimitBucket","tags":["Risk"],"summary":"Create a rate limit bucket","description":"At most 100 buckets per environment; names are unique in it.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskLimitBucketRequest"}}}},"responses":{"201":{"description":"The new bucket.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskLimitBucket"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`), the name is taken (`limit_bucket_name_taken`) or the environment already has 100 buckets (`too_many_limit_buckets`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]},"get":{"operationId":"listRiskLimitBuckets","tags":["Risk"],"summary":"List rate limit buckets","description":"Every bucket of the API key's environment, by name.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The buckets.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskLimitBucketList"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/CossVersion"}]}},"/v1/risk/limit_buckets/{id}":{"get":{"operationId":"getRiskLimitBucket","tags":["Risk"],"summary":"Retrieve a rate limit bucket","description":"One of the rate limit buckets you defined for `POST /v1/risk/limit`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The bucket's id.","examples":["rsklb_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The bucket's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The bucket.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskLimitBucket"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateRiskLimitBucket","tags":["Risk"],"summary":"Update a rate limit bucket","description":"Changes the fields given; the next check uses them. Keys keep what they spent, so a smaller bucket can deny a key until it refills.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The bucket's id.","examples":["rsklb_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The bucket's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRiskLimitBucketRequest"}}}},"responses":{"200":{"description":"The bucket, updated.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskLimitBucket"}}}},"400":{"description":"The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 5 MB (`payload_too_large`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is not sent as `application/json` (`unsupported_media_type`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`validation_error`, see `issues`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteRiskLimitBucket","tags":["Risk"],"summary":"Delete a rate limit bucket","description":"Checks naming it get a 404 from then on; a new bucket with its name starts empty.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The bucket's id.","examples":["rsklb_01k7c8m4q2f3e9v6t5r1n0p8yz"]},"required":true,"description":"The bucket's id.","name":"id","in":"path"},{"$ref":"#/components/parameters/CossVersion"}],"responses":{"200":{"description":"The bucket was deleted.","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Coss-Version":{"description":"The API version this response is rendered in.","schema":{"type":"string","examples":["2026-10-10"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedRiskLimitBucket"}}}},"400":{"description":"The `Coss-Version` header names an unknown API version (`invalid_api_version`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, revoked or expired (`authentication_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id exists in the API key's environment (`not_found`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error (`api_error` / `internal_error`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The API key could not be verified right now; retry (`service_unavailable`).","headers":{"X-Request-Id":{"description":"Unique id of this request. Include it when contacting support.","schema":{"type":"string","examples":["req_01k7c8m4q2f3e9v6t5r1n0p8yz"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}