{
  "openapi": "3.1.0",
  "info": {
    "title": "Local Flywheel API",
    "version": "2.62.1",
    "description": "Run a sub-account: leads, deal value and won/lost, pipeline stages, bookings and calendars, texts and emails, the inbox, calls, forms, automations and settings.\n\nAuthenticate with `Authorization: Bearer zu-...` (Settings → API). Every response is `{ success, data, error }`.\nA key works inside its own sub-account only, so `workspace_id` can be left out everywhere.\nMCP server: https://api.localflywheel.com/mcp\n\n### Authentication\nSend your key as `Authorization: Bearer zu-...`. Admins of a sub-account create keys in the CRM under Settings → API. A key works inside its own sub-account only: you can leave out `workspace_id` everywhere, a different one is ignored, and records of any other sub-account answer 404. Access levels: Read only, Read and write, or Full access (deleting things, team members and anything that sends lead data outside the account). Every call also follows the role of the person who made the key: a key keeps working only while they are an admin of the sub-account.\n\n### Idempotency\nEvery write (POST, PUT, PATCH, DELETE) accepts `Idempotency-Key: <your-unique-string>`. Replaying the same key with the same body within 24 hours returns the original response instead of doing the work twice (no second message, no second booking); the same key with a different body answers 409. Use a fresh key per logical operation, not per retry.\n\n### Rate limits\nEvery response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. On 429 a `Retry-After` header (and `retry_after_seconds` in the body) tells you how long to wait. The limit is per key, per minute: 120 by default, adjustable from 1 to 600 in Settings → API.\n\n### Pagination\nList endpoints accept `limit` (default 50, max 200) and return the newest rows first. GET /v1/messages is the one endpoint with a cursor: pass `cursor` (or `since`) and follow `next_cursor` to walk forward without duplicates.\n\n### Messaging safety limits\nTo protect number reputation, each sub-account can message at most 300 unique contacts per UTC day (plus per-minute burst and daily segment caps). Replying to a contact you already messaged that day does not consume another contact slot. Messaging endpoints return X-Contacts-Limit, X-Contacts-Used, X-Contacts-Remaining and X-Contacts-Reset; over the cap sends answer 429 with `code: \"sms_limit\"` and a `limit` object. Check the current state any time with GET /v1/messages/limits. Need a higher ceiling? Request a limit increase from Settings → Messaging and we'll review it.\n\n### Responses and errors\nSuccess is `{ success: true, data, error: null }`. Errors are `{ success: false, data: null, error: string, details?: object }` with a matching HTTP status; scope, rate-limit and budget errors put a machine-readable code in `error` (`scope_denied`, `rate_limit_exceeded`, `credit_limit_exceeded`) and the explanation in `message`. Branch on the status and the code, not on message text.\n"
  },
  "servers": [
    {
      "url": "https://api.localflywheel.com",
      "description": "Production"
    }
  ],
  "x-webhooks": {
    "workspaceEvents": [
      {
        "event": "lead.created",
        "description": "A lead was captured for this sub-account. Payload is a full lead snapshot including custom form fields."
      },
      {
        "event": "lead.updated",
        "description": "The lead's status or pipeline stage changed (other field edits do not fire it). Payload carries previous_status, status, previous_stage_key and stage_key."
      },
      {
        "event": "lead.qualified",
        "description": "The lead was marked qualified."
      },
      {
        "event": "appointment.booked",
        "description": "An appointment was booked for the lead."
      },
      {
        "event": "appointment.rescheduled",
        "description": "An appointment moved to a new time, in the CRM calendar, through the API, by an inbound webhook or by the customer on their appointment page. Payload carries booking_id, lead_id, the new starts_at / ends_at, timezone, host, calendar, meeting and moved_via (app, api, inbound_webhook or customer)."
      },
      {
        "event": "appointment.cancelled",
        "description": "A booked appointment was cancelled."
      },
      {
        "event": "message.received",
        "description": "An inbound SMS or email arrived on this sub-account's number or inbox. Payload carries message_id, lead_id, channel, direction, body, from/to and media_urls, and `transport` (imessage or mac_sms) when it came in on one of the sub-account's iMessage Macs."
      },
      {
        "event": "message.sent",
        "description": "An outbound SMS or email was handed to the carrier or mail provider — manual, automated or API-sent. Texts carry `transport`: sms from the business number, imessage or mac_sms when one of the sub-account's Macs sent it."
      },
      {
        "event": "message.failed",
        "description": "An outbound message could not be sent. Payload includes the error and, when the contact-safety cap was hit, a `limit` object."
      },
      {
        "event": "call.completed",
        "description": "An AI receptionist call ended (once per call, after its recap is written; practice calls from Settings excluded). Payload carries call_id, lead_id (null for a caller with no lead), from/to, status, duration_sec, outcome, summary, booking_id and started_at / ended_at. The transcript and recording: GET /v1/calls/{call_id}."
      },
      {
        "event": "deal.updated",
        "description": "A lead was marked won, or a won lead's amount or plan changed later (an amount added from Ad Insights, a plan edited). Payload carries deal_type (one_time or plan), deal_value_cents (the first payment), deal_plan_cents, deal_plan_interval, deal_monthly_cents and deal_expected_total_cents, plus the lead snapshot. Every lead event's snapshot carries the same deal fields."
      }
    ],
    "signature": {
      "header": "X-Webhook-Signature",
      "format": "sha256=<hex hmac>",
      "description": "Each delivery is signed with HMAC-SHA256 over the exact raw request body using the webhook's secret (shown once when it is created). Compute the HMAC over the raw bytes, before JSON parsing, and compare in constant time. `X-Webhook-Event` carries the event name and `X-Webhook-Delivery` a unique delivery id you can use to de-duplicate retries."
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "CRM leads"
    },
    {
      "name": "Messaging"
    },
    {
      "name": "Bookings"
    },
    {
      "name": "Members"
    },
    {
      "name": "Smart forms"
    },
    {
      "name": "CRM automations"
    },
    {
      "name": "Workspaces"
    },
    {
      "name": "Setup"
    },
    {
      "name": "Offers"
    },
    {
      "name": "Calendars & hours"
    },
    {
      "name": "Team busy times"
    },
    {
      "name": "Pipeline & fields"
    },
    {
      "name": "Routing & alerts"
    },
    {
      "name": "Lead sources & webhooks"
    },
    {
      "name": "AI agent"
    },
    {
      "name": "Invoices & reviews"
    },
    {
      "name": "Website widget"
    },
    {
      "name": "Short links"
    },
    {
      "name": "Ads & Google"
    },
    {
      "name": "Meta"
    },
    {
      "name": "Smart pages"
    },
    {
      "name": "Website Analytics"
    },
    {
      "name": "Calls"
    },
    {
      "name": "Media"
    },
    {
      "name": "Contracts"
    },
    {
      "name": "Sub-account setup"
    },
    {
      "name": "Dashboard"
    },
    {
      "name": "Inbox"
    },
    {
      "name": "AI Brain"
    },
    {
      "name": "Email marketing"
    },
    {
      "name": "Proposals"
    },
    {
      "name": "Support"
    },
    {
      "name": "Account"
    },
    {
      "name": "Click Guard"
    },
    {
      "name": "Call Tracking"
    },
    {
      "name": "Reports"
    },
    {
      "name": "Reward games"
    },
    {
      "name": "Loyalty cards"
    }
  ],
  "paths": {
    "/v1/leads": {
      "get": {
        "operationId": "list_leads",
        "tags": [
          "CRM leads"
        ],
        "summary": "List and filter leads",
        "description": "Newest first.\n\n- Filter by tags (`tag_match=any` returns leads with at least one of the tags, `all` leads with every one), status, pipeline stage, assignee, State, leads or existing customers (`existing_customer`; both by default), people who only chatted (`chat_only`; both by default), a name / email / phone search and a created-since time.\n- Each lead carries `existing_customer`, `chat_only` (only messaged from website chat, Instagram or Messenger and shared no phone or email yet: a conversation in Messages, left off the Leads page and every lead count), `inquiry` (the CRM's Inquiry column), `address`, `city`, `state`, `zip`, `custom_fields`, `tags` and `stage` (the pipeline stage it shows in).\n- Page with `limit` and `offset`: `next_offset` is set while there are more.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": false,
            "description": "Restrict to one sub-account (a key restricted to one sub-account always uses its own).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "description": "Tag names, comma-separated (tags=VIP,Roof), or a JSON array (tags=[\"Roof, metal\",\"VIP\"]) when a name has a comma. Max 10.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag_match",
            "in": "query",
            "required": false,
            "description": "any (default): at least one of the tags. all: every tag.",
            "schema": {
              "type": "string",
              "enum": [
                "any",
                "all"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "One or more statuses, comma-separated: new, contacted, qualified, booked, won, lost, spam, partial.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage_key",
            "in": "query",
            "required": false,
            "description": "Pipeline stage key from GET /v1/stages.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assigned_to",
            "in": "query",
            "required": false,
            "description": "A user id (GET /v1/members): leads assigned to them. \"me\": the key's own user. \"unassigned\": nobody's.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "State / province / region as saved on the lead, comma-separated (state=TX,FL), like Leads > Filter > State. A name finds its code too (\"Texas\" finds TX). \"none\": leads with no State. Max 20.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "existing_customer",
            "in": "query",
            "required": false,
            "description": "true: only existing customers (the Leads page's Existing customers view). false: only leads. Leave out for both.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "chat_only",
            "in": "query",
            "required": false,
            "description": "false: leave out people who only messaged (website chat, Instagram, Messenger) and shared no phone or email yet, as the Leads page does. true: only them. Leave out for both.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "The Leads page's search: every word (any order) must be somewhere in the lead: name, email, phone, campaign, ad, notes, address, answers or custom fields. A phone number matches however it's typed.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO timestamp: only leads created at or after it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Default 50, max 200.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many leads; pass next_offset from the previous page.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "leads": [
                      {
                        "id": "lead-uuid",
                        "workspace_id": "ws-uuid",
                        "full_name": "Jane Doe",
                        "email": "jane@example.com",
                        "phone": "+14155550123",
                        "phone_label": "Mobile",
                        "extra_phones": [
                          {
                            "phone": "+14155550188",
                            "label": "Home"
                          }
                        ],
                        "source": "api",
                        "status": "contacted",
                        "stage_key": "quote_sent",
                        "existing_customer": false,
                        "score": null,
                        "assigned_to": null,
                        "ad_name": null,
                        "campaign_name": null,
                        "deal_value_cents": null,
                        "deal_currency": "USD",
                        "created_at": "2026-09-23T15:00:00Z",
                        "updated_at": "2026-09-23T15:05:00Z",
                        "last_activity_at": "2026-09-23T15:05:00Z",
                        "stage": "quote_sent",
                        "inquiry": "Roof replacement quote",
                        "address": "12 Main St",
                        "city": "Pittsburgh",
                        "state": "PA",
                        "zip": "15213",
                        "custom_fields": {
                          "roof_type": "Metal",
                          "roof_age_years": 18
                        },
                        "tags": [
                          "Spring promo",
                          "VIP"
                        ]
                      }
                    ],
                    "has_more": false,
                    "next_offset": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_lead",
        "tags": [
          "CRM leads"
        ],
        "summary": "Create a lead",
        "description": "Needs `workspace_id` plus at least one of `full_name`, email or phone. Besides the lead's columns you can set `inquiry`, `address`, `city`, `state`, `zip`, `custom_fields` and `tags`.\n\n- The lead and its tags are saved together, so automations that filter on tags see them; each tag fires the `lead.tag_added` automation trigger.\n- A lead with the same phone (last 10 digits) or email already in the sub-account answers 409 with its `lead_id` and `matched_on` in `details`: update that lead instead.\n- A field the API does not know answers 400 (it is never silently dropped).\n- By default the intake doesn't run (no first text, follow-ups, team alert or Instant Lead Connect); `run_intake: true` works it like any new lead from a form and `intake` in the response says what ran.\n- Either way it is a new lead to the rest of the CRM, as one added by hand is: automations that start on a new lead or a tag run, AI calling campaigns that take new leads pick it up, and the `lead.created` webhook fires.\n- Not with `existing_customer: true`: a past customer is no new lead, so none of that runs, it stays out of the pipeline and the lead numbers, and `run_intake` is refused (400).\n- Returns the lead as `GET /v1/leads/{lead_id}` shows it.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "full_name": {
                    "type": "string",
                    "description": "Lead name."
                  },
                  "email": {
                    "type": "string",
                    "description": "Email address."
                  },
                  "phone": {
                    "type": "string",
                    "description": "10-digit US number or + and a country code; stored as E.164."
                  },
                  "phone_label": {
                    "type": "string",
                    "description": "The main phone's label: Mobile, Home, Work, Other or your own words (40 characters)."
                  },
                  "extra_phones": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The lead's other phone numbers, up to 10: numbers, or {phone, label} objects. Replaces the whole list; [] or null clears it. A text can go to any of them (POST /v1/messages to), and a text or call from one finds this lead."
                  },
                  "source": {
                    "type": "string",
                    "description": "Where the lead came from. Defaults to api.",
                    "enum": [
                      "meta_lead_ad",
                      "manual",
                      "website_form",
                      "import",
                      "api",
                      "other",
                      "sms_inbound",
                      "email_inbound",
                      "webhook",
                      "smart_form",
                      "smart_form_partial",
                      "site_widget",
                      "instagram",
                      "messenger",
                      "review_funnel",
                      "calendly",
                      "acuity",
                      "google_calendar"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "description": "Base lead status. To move a lead in the pipeline, send stage_key instead.",
                    "enum": [
                      "new",
                      "contacted",
                      "qualified",
                      "booked",
                      "won",
                      "lost",
                      "spam",
                      "partial"
                    ]
                  },
                  "stage_key": {
                    "type": "string",
                    "description": "Pipeline stage key from GET /v1/stages. A stage also sets the status it stands for."
                  },
                  "existing_customer": {
                    "type": "boolean",
                    "description": "true = someone who was already a customer (a past customer list), not a lead, like Leads > Import \"Existing customers\": out of the pipeline and every lead count, and adding them starts no new-lead automations, AI calls or webhooks. A new one is won with no sale date (so no sale is counted) unless you send status or stage_key. false moves them back to leads. Changing it never moves the stage."
                  },
                  "score": {
                    "type": "number",
                    "description": "A number 0-100 that is yours to set, e.g. a counter your automations keep. Nothing writes it for you (AI lead scoring is off)."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Internal notes."
                  },
                  "assigned_to": {
                    "type": "string",
                    "description": "User id of someone in the sub-account (GET /v1/members). The agency owner only with the owner's own key (the app never offers them to the sub-account's people; a lead already on them may stay). null unassigns. A change is logged on the lead's timeline (Lead assigned / Lead unassigned), as in the app."
                  },
                  "ad_name": {
                    "type": "string",
                    "description": "Ad the lead came from."
                  },
                  "campaign_name": {
                    "type": "string",
                    "description": "Campaign the lead came from."
                  },
                  "utm_source": {
                    "type": "string",
                    "description": "UTM source."
                  },
                  "utm_medium": {
                    "type": "string",
                    "description": "UTM medium."
                  },
                  "utm_campaign": {
                    "type": "string",
                    "description": "UTM campaign."
                  },
                  "utm_term": {
                    "type": "string",
                    "description": "UTM term."
                  },
                  "utm_content": {
                    "type": "string",
                    "description": "UTM content."
                  },
                  "landing_url": {
                    "type": "string",
                    "description": "Page the lead converted on."
                  },
                  "referrer_url": {
                    "type": "string",
                    "description": "Referring page."
                  },
                  "attribution_channel": {
                    "type": "string",
                    "description": "e.g. meta, google, organic, direct."
                  },
                  "gclid": {
                    "type": "string",
                    "description": "Google Ads click id. A lead with one is sent back to the sub-account's Google Ads by its click when it books or is won (CRM conversions)."
                  },
                  "gbraid": {
                    "type": "string",
                    "description": "Google Ads app-to-web click id."
                  },
                  "wbraid": {
                    "type": "string",
                    "description": "Google Ads web-to-app click id."
                  },
                  "fbclid": {
                    "type": "string",
                    "description": "Facebook click id."
                  },
                  "msclkid": {
                    "type": "string",
                    "description": "Microsoft Ads click id."
                  },
                  "deal_value_cents": {
                    "type": "number",
                    "description": "Deal value in cents: on a won job, what the customer paid (the Sales report's Sold, and the revenue sent to Meta)."
                  },
                  "deal_currency": {
                    "type": "string",
                    "description": "3-letter currency code. Default USD."
                  },
                  "deal_parts_cents": {
                    "type": "number",
                    "description": "Won job: what the parts cost, in cents (Sales report)."
                  },
                  "deal_tip_cents": {
                    "type": "number",
                    "description": "Won job: the tip the technician got, in cents."
                  },
                  "deal_sold_by": {
                    "type": "string",
                    "description": "Won job: the user id of the technician credited with the sale (GET /v1/members). null = whoever the lead is assigned to."
                  },
                  "deal_won_at": {
                    "type": "string",
                    "description": "When the job was won (ISO 8601). Set for you when status becomes won; send it to date a sale yourself."
                  },
                  "deal_type": {
                    "type": "string",
                    "description": "Plans & memberships: what the customer bought, one_time (a job) or plan (a plan or membership that pays again). null = one-time. A deal_plan_cents sent alone makes it a plan; one_time clears the plan.",
                    "enum": [
                      "one_time",
                      "plan"
                    ]
                  },
                  "deal_plan_cents": {
                    "type": "number",
                    "description": "Plan: its price in cents, charged every deal_plan_interval. deal_value_cents is the first payment (the plan price when you leave it out)."
                  },
                  "deal_plan_interval": {
                    "type": "string",
                    "description": "Plan: how often it's charged. Default month.",
                    "enum": [
                      "month",
                      "quarter",
                      "year"
                    ]
                  },
                  "deal_plan_start_date": {
                    "type": "string",
                    "description": "Plan: when it starts (YYYY-MM-DD). Default today."
                  },
                  "deal_plan_months": {
                    "type": "number",
                    "description": "Plan: how many months it runs (1-600). null = no end date: the business's default length counts (12 months unless changed in Settings > Features). Leads return deal_monthly_cents and deal_expected_total_cents (first payment + the plan price for the rest of its length)."
                  },
                  "inquiry": {
                    "type": "string",
                    "description": "What the lead asked about: the Inquiry column in the CRM (max 500). Without it the CRM shows the form or ad offer, then General inquiry."
                  },
                  "address": {
                    "type": "string",
                    "description": "Street address."
                  },
                  "city": {
                    "type": "string",
                    "description": "City."
                  },
                  "state": {
                    "type": "string",
                    "description": "State or region. A US state, Canadian province or Australian state is stored as its code (\"Texas\" -> \"TX\"), a Mexican state by name, like every other intake; the list follows the lead's country (its phone number, else the sub-account's country). Anything else is kept as sent."
                  },
                  "zip": {
                    "type": "string",
                    "description": "ZIP or postal code."
                  },
                  "custom_fields": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Custom field values keyed by field_key (GET /v1/custom-fields); a field's label also works. Values are checked against the field type: number/money/rating numbers, boolean true/false, date YYYY-MM-DD, datetime ISO 8601, select one of its options, multiselect a list of options. null or \"\" clears a value; fields you leave out keep their value."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tag names. New names are created in the sub-account (matched ignoring case). Max 50."
                  },
                  "run_intake": {
                    "type": "boolean",
                    "description": "Default false. true = work the lead like a new lead from a form: the first text (when Auto-greet is on; it waits while someone is on a call with the lead), follow-ups, team alert, Instant Lead Connect."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "full_name": "Jane Doe",
                "phone": "+14155550123",
                "email": "jane@example.com",
                "inquiry": "Roof replacement quote",
                "address": "12 Main St",
                "city": "Pittsburgh",
                "state": "PA",
                "zip": "15213",
                "custom_fields": {
                  "roof_type": "Metal",
                  "roof_age_years": 18
                },
                "tags": [
                  "Spring promo",
                  "VIP"
                ],
                "run_intake": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead": {
                      "id": "lead-uuid",
                      "workspace_id": "ws-uuid",
                      "full_name": "Jane Doe",
                      "email": "jane@example.com",
                      "phone": "+14155550123",
                      "phone_label": "Mobile",
                      "extra_phones": [
                        {
                          "phone": "+14155550188",
                          "label": "Home"
                        }
                      ],
                      "source": "api",
                      "status": "contacted",
                      "stage_key": "quote_sent",
                      "existing_customer": false,
                      "score": null,
                      "assigned_to": null,
                      "ad_name": null,
                      "campaign_name": null,
                      "deal_value_cents": null,
                      "deal_currency": "USD",
                      "created_at": "2026-09-23T15:00:00Z",
                      "updated_at": "2026-09-23T15:05:00Z",
                      "last_activity_at": "2026-09-23T15:05:00Z",
                      "stage": "quote_sent",
                      "inquiry": "Roof replacement quote",
                      "address": "12 Main St",
                      "city": "Pittsburgh",
                      "state": "PA",
                      "zip": "15213",
                      "custom_fields": {
                        "roof_type": "Metal",
                        "roof_age_years": 18
                      },
                      "tags": [
                        "Spring promo",
                        "VIP"
                      ]
                    },
                    "intake": {
                      "ran": true,
                      "greeted": true
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}": {
      "get": {
        "operationId": "get_lead",
        "tags": [
          "CRM leads"
        ],
        "summary": "Get one lead",
        "description": "The lead with every column, its `raw_payload`, the flattened `inquiry`, `address`, `city`, `state`, `zip`, `custom_fields`, `tags` and `stage`, plus its 50 most recent timeline events.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead": {
                      "id": "lead-uuid",
                      "workspace_id": "ws-uuid",
                      "full_name": "Jane Doe",
                      "email": "jane@example.com",
                      "phone": "+14155550123",
                      "phone_label": "Mobile",
                      "extra_phones": [
                        {
                          "phone": "+14155550188",
                          "label": "Home"
                        }
                      ],
                      "source": "api",
                      "status": "contacted",
                      "stage_key": "quote_sent",
                      "existing_customer": false,
                      "score": null,
                      "assigned_to": null,
                      "ad_name": null,
                      "campaign_name": null,
                      "deal_value_cents": null,
                      "deal_currency": "USD",
                      "created_at": "2026-09-23T15:00:00Z",
                      "updated_at": "2026-09-23T15:05:00Z",
                      "last_activity_at": "2026-09-23T15:05:00Z",
                      "stage": "quote_sent",
                      "inquiry": "Roof replacement quote",
                      "address": "12 Main St",
                      "city": "Pittsburgh",
                      "state": "PA",
                      "zip": "15213",
                      "custom_fields": {
                        "roof_type": "Metal",
                        "roof_age_years": 18
                      },
                      "tags": [
                        "Spring promo",
                        "VIP"
                      ]
                    },
                    "events": [
                      {
                        "id": "event-uuid",
                        "event_type": "note",
                        "body": "Lead created via API",
                        "created_at": "2026-09-23T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_lead",
        "tags": [
          "CRM leads"
        ],
        "summary": "Update a lead",
        "description": "Send only what changes; null or \"\" clears a value. `custom_fields` merges: values you leave out are kept.\n\n- `tags` REPLACES all of the lead's tags; `add_tags` and `remove_tags` change only those (applied in that order: tags, `add_tags`, `remove_tags`).\n- A body with only tag changes is fine.\n- `stage_key` moves the lead in the pipeline and sets the status that stage stands for.\n- A field the API does not know answers 400.\n- Returns the updated lead.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "full_name": {
                    "type": "string",
                    "description": "Lead name."
                  },
                  "email": {
                    "type": "string",
                    "description": "Email address."
                  },
                  "phone": {
                    "type": "string",
                    "description": "10-digit US number or + and a country code; stored as E.164."
                  },
                  "phone_label": {
                    "type": "string",
                    "description": "The main phone's label: Mobile, Home, Work, Other or your own words (40 characters)."
                  },
                  "extra_phones": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The lead's other phone numbers, up to 10: numbers, or {phone, label} objects. Replaces the whole list; [] or null clears it. A text can go to any of them (POST /v1/messages to), and a text or call from one finds this lead."
                  },
                  "source": {
                    "type": "string",
                    "description": "Where the lead came from. Defaults to api.",
                    "enum": [
                      "meta_lead_ad",
                      "manual",
                      "website_form",
                      "import",
                      "api",
                      "other",
                      "sms_inbound",
                      "email_inbound",
                      "webhook",
                      "smart_form",
                      "smart_form_partial",
                      "site_widget",
                      "instagram",
                      "messenger",
                      "review_funnel",
                      "calendly",
                      "acuity",
                      "google_calendar"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "description": "Base lead status. To move a lead in the pipeline, send stage_key instead.",
                    "enum": [
                      "new",
                      "contacted",
                      "qualified",
                      "booked",
                      "won",
                      "lost",
                      "spam",
                      "partial"
                    ]
                  },
                  "stage_key": {
                    "type": "string",
                    "description": "Pipeline stage key from GET /v1/stages. A stage also sets the status it stands for."
                  },
                  "existing_customer": {
                    "type": "boolean",
                    "description": "true = someone who was already a customer (a past customer list), not a lead, like Leads > Import \"Existing customers\": out of the pipeline and every lead count, and adding them starts no new-lead automations, AI calls or webhooks. A new one is won with no sale date (so no sale is counted) unless you send status or stage_key. false moves them back to leads. Changing it never moves the stage."
                  },
                  "score": {
                    "type": "number",
                    "description": "A number 0-100 that is yours to set, e.g. a counter your automations keep. Nothing writes it for you (AI lead scoring is off)."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Internal notes."
                  },
                  "assigned_to": {
                    "type": "string",
                    "description": "User id of someone in the sub-account (GET /v1/members). The agency owner only with the owner's own key (the app never offers them to the sub-account's people; a lead already on them may stay). null unassigns. A change is logged on the lead's timeline (Lead assigned / Lead unassigned), as in the app."
                  },
                  "ad_name": {
                    "type": "string",
                    "description": "Ad the lead came from."
                  },
                  "campaign_name": {
                    "type": "string",
                    "description": "Campaign the lead came from."
                  },
                  "utm_source": {
                    "type": "string",
                    "description": "UTM source."
                  },
                  "utm_medium": {
                    "type": "string",
                    "description": "UTM medium."
                  },
                  "utm_campaign": {
                    "type": "string",
                    "description": "UTM campaign."
                  },
                  "utm_term": {
                    "type": "string",
                    "description": "UTM term."
                  },
                  "utm_content": {
                    "type": "string",
                    "description": "UTM content."
                  },
                  "landing_url": {
                    "type": "string",
                    "description": "Page the lead converted on."
                  },
                  "referrer_url": {
                    "type": "string",
                    "description": "Referring page."
                  },
                  "attribution_channel": {
                    "type": "string",
                    "description": "e.g. meta, google, organic, direct."
                  },
                  "gclid": {
                    "type": "string",
                    "description": "Google Ads click id. A lead with one is sent back to the sub-account's Google Ads by its click when it books or is won (CRM conversions)."
                  },
                  "gbraid": {
                    "type": "string",
                    "description": "Google Ads app-to-web click id."
                  },
                  "wbraid": {
                    "type": "string",
                    "description": "Google Ads web-to-app click id."
                  },
                  "fbclid": {
                    "type": "string",
                    "description": "Facebook click id."
                  },
                  "msclkid": {
                    "type": "string",
                    "description": "Microsoft Ads click id."
                  },
                  "deal_value_cents": {
                    "type": "number",
                    "description": "Deal value in cents: on a won job, what the customer paid (the Sales report's Sold, and the revenue sent to Meta)."
                  },
                  "deal_currency": {
                    "type": "string",
                    "description": "3-letter currency code. Default USD."
                  },
                  "deal_parts_cents": {
                    "type": "number",
                    "description": "Won job: what the parts cost, in cents (Sales report)."
                  },
                  "deal_tip_cents": {
                    "type": "number",
                    "description": "Won job: the tip the technician got, in cents."
                  },
                  "deal_sold_by": {
                    "type": "string",
                    "description": "Won job: the user id of the technician credited with the sale (GET /v1/members). null = whoever the lead is assigned to."
                  },
                  "deal_won_at": {
                    "type": "string",
                    "description": "When the job was won (ISO 8601). Set for you when status becomes won; send it to date a sale yourself."
                  },
                  "deal_type": {
                    "type": "string",
                    "description": "Plans & memberships: what the customer bought, one_time (a job) or plan (a plan or membership that pays again). null = one-time. A deal_plan_cents sent alone makes it a plan; one_time clears the plan.",
                    "enum": [
                      "one_time",
                      "plan"
                    ]
                  },
                  "deal_plan_cents": {
                    "type": "number",
                    "description": "Plan: its price in cents, charged every deal_plan_interval. deal_value_cents is the first payment (the plan price when you leave it out)."
                  },
                  "deal_plan_interval": {
                    "type": "string",
                    "description": "Plan: how often it's charged. Default month.",
                    "enum": [
                      "month",
                      "quarter",
                      "year"
                    ]
                  },
                  "deal_plan_start_date": {
                    "type": "string",
                    "description": "Plan: when it starts (YYYY-MM-DD). Default today."
                  },
                  "deal_plan_months": {
                    "type": "number",
                    "description": "Plan: how many months it runs (1-600). null = no end date: the business's default length counts (12 months unless changed in Settings > Features). Leads return deal_monthly_cents and deal_expected_total_cents (first payment + the plan price for the rest of its length)."
                  },
                  "inquiry": {
                    "type": "string",
                    "description": "What the lead asked about: the Inquiry column in the CRM (max 500). Without it the CRM shows the form or ad offer, then General inquiry."
                  },
                  "address": {
                    "type": "string",
                    "description": "Street address."
                  },
                  "city": {
                    "type": "string",
                    "description": "City."
                  },
                  "state": {
                    "type": "string",
                    "description": "State or region. A US state, Canadian province or Australian state is stored as its code (\"Texas\" -> \"TX\"), a Mexican state by name, like every other intake; the list follows the lead's country (its phone number, else the sub-account's country). Anything else is kept as sent."
                  },
                  "zip": {
                    "type": "string",
                    "description": "ZIP or postal code."
                  },
                  "custom_fields": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Custom field values keyed by field_key (GET /v1/custom-fields); a field's label also works. Values are checked against the field type: number/money/rating numbers, boolean true/false, date YYYY-MM-DD, datetime ISO 8601, select one of its options, multiselect a list of options. null or \"\" clears a value; fields you leave out keep their value."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "REPLACES all of the lead's tags ([] removes them all). To change only some, use add_tags / remove_tags."
                  },
                  "add_tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tag names to add; the lead's other tags stay. New names are created."
                  },
                  "remove_tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tag names to remove."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "add_tags": [
                  "Hot lead"
                ],
                "remove_tags": [
                  "Cold"
                ],
                "stage_key": "quote_sent",
                "custom_fields": {
                  "roof_type": "Tile"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead": {
                      "id": "lead-uuid",
                      "workspace_id": "ws-uuid",
                      "full_name": "Jane Doe",
                      "email": "jane@example.com",
                      "phone": "+14155550123",
                      "phone_label": "Mobile",
                      "extra_phones": [
                        {
                          "phone": "+14155550188",
                          "label": "Home"
                        }
                      ],
                      "source": "api",
                      "status": "contacted",
                      "stage_key": "quote_sent",
                      "existing_customer": false,
                      "score": null,
                      "assigned_to": null,
                      "ad_name": null,
                      "campaign_name": null,
                      "deal_value_cents": null,
                      "deal_currency": "USD",
                      "created_at": "2026-09-23T15:00:00Z",
                      "updated_at": "2026-09-23T15:05:00Z",
                      "last_activity_at": "2026-09-23T15:05:00Z",
                      "stage": "quote_sent",
                      "inquiry": "Roof replacement quote",
                      "address": "12 Main St",
                      "city": "Pittsburgh",
                      "state": "PA",
                      "zip": "15213",
                      "custom_fields": {
                        "roof_type": "Metal",
                        "roof_age_years": 18
                      },
                      "tags": [
                        "Spring promo",
                        "VIP"
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_lead",
        "tags": [
          "CRM leads"
        ],
        "summary": "Delete a lead",
        "description": "With `delete_appointments`=true its appointments go first, each the way the calendar deletes one: the synced Google / Outlook event, the customer's invite (cancelled if it was still on), its reminder texts, then the appointment; if one can't be deleted the lead is kept and the answer says how many went. Without it the appointments stay on the calendar with no lead, as before.\n\nRequired scope: `leads:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "delete_appointments",
            "in": "query",
            "required": false,
            "description": "Also delete the lead's appointments (the app's \"Also delete their appointments\").",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "appointments_deleted": 2
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/timeline": {
      "get": {
        "operationId": "lead_timeline",
        "tags": [
          "CRM leads"
        ],
        "summary": "Lead activity timeline",
        "description": "Required scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Default 50.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/notes": {
      "post": {
        "operationId": "create_lead_note",
        "tags": [
          "CRM leads"
        ],
        "summary": "Add a note to a lead",
        "description": "mentions tags teammates like @Name in the app's note box: each one on the sub-account's team who can see the lead gets an email and a push with the note and a link to the conversation (replies go to you); the answer lists who was told and who was skipped and why (`not_on_team`, `cant_see_lead`).\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "Note text."
                  },
                  "actor_label": {
                    "type": "string",
                    "description": "Who the note is from."
                  },
                  "mentions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 20 user ids to tag (GET /v1/members)."
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": true
              },
              "example": {
                "body": "@Sam can you call her back after 5?",
                "mentions": [
                  "uuid"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "event": {
                      "id": "uuid",
                      "event_type": "note",
                      "body": "@Sam can you call her back after 5?"
                    },
                    "mentions": {
                      "tagged": [
                        {
                          "user_id": "uuid",
                          "name": "Sam Tech"
                        }
                      ],
                      "skipped": []
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/stage": {
      "post": {
        "operationId": "set_lead_stage",
        "tags": [
          "CRM leads"
        ],
        "summary": "Move a lead to a pipeline stage",
        "description": "PATCH on the same path does the same.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stage_key": {
                    "type": "string",
                    "description": "Stage key from GET /v1/stages."
                  }
                },
                "required": [
                  "stage_key"
                ],
                "additionalProperties": true
              },
              "example": {
                "stage_key": "booked"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/stages": {
      "get": {
        "operationId": "list_stages",
        "tags": [
          "CRM leads"
        ],
        "summary": "List pipeline stages",
        "description": "Required scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_stage",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Add a pipeline stage",
        "description": "`behavior` is what the stage means for reporting. The key is made from the label and never changes.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "label": {
                    "type": "string",
                    "description": "Stage name (max 40)."
                  },
                  "behavior": {
                    "type": "string",
                    "description": "Default contacted.",
                    "enum": [
                      "new",
                      "contacted",
                      "booked",
                      "won",
                      "lost"
                    ]
                  },
                  "color": {
                    "type": "string",
                    "description": "Defaults to the first unused colour.",
                    "enum": [
                      "blue",
                      "amber",
                      "violet",
                      "cyan",
                      "emerald",
                      "rose",
                      "teal",
                      "orange",
                      "pink",
                      "indigo",
                      "lime",
                      "slate"
                    ]
                  },
                  "manual_only": {
                    "type": "boolean",
                    "description": "Moving a lead here does not change its status."
                  }
                },
                "required": [
                  "workspace_id",
                  "label"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "label": "Quote sent",
                "behavior": "contacted"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tags": {
      "get": {
        "operationId": "list_tags",
        "tags": [
          "CRM leads"
        ],
        "summary": "List lead tags",
        "description": "Every tag in the sub-account and how many leads carry it. A tag is created automatically the first time you send its name in a lead's tags or `add_tags`.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "tags": [
                      {
                        "id": "tag-uuid",
                        "name": "VIP",
                        "color": "slate",
                        "lead_count": 12,
                        "created_at": "2026-09-01T10:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_tag",
        "tags": [
          "CRM leads"
        ],
        "summary": "Make a tag",
        "description": "A tag on its own, before any lead carries it. Names match in any case: a name that already exists answers that tag with created false (200) and changes nothing, so the call is safe to repeat. Up to 60 characters, no commas.\n\nWho can call it: Any member, as when tagging a lead in the app.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "The tag's name."
                  },
                  "color": {
                    "type": "string",
                    "description": "Default slate.",
                    "enum": [
                      "blue",
                      "amber",
                      "violet",
                      "cyan",
                      "emerald",
                      "rose",
                      "teal",
                      "orange",
                      "pink",
                      "indigo",
                      "lime",
                      "slate"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Hot lead",
                "color": "rose"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "tag": {
                      "id": "uuid",
                      "name": "Hot lead",
                      "color": "rose"
                    },
                    "created": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tags/{tag_id}": {
      "patch": {
        "operationId": "update_tag",
        "tags": [
          "CRM leads"
        ],
        "summary": "Rename or recolor a tag",
        "description": "Settings > Tags. A new name (60 characters, no commas, not another tag's name: merge them instead) and/or a color.\n\nA rename also rewrites every automation that names the tag (Add / Remove tag steps, the Tag added trigger, tag conditions) unless `update_automations` is false.\n\nWho can call it: Owners and admins.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag_id",
            "in": "path",
            "required": true,
            "description": "The tag (GET /v1/tags).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The new name."
                  },
                  "color": {
                    "type": "string",
                    "description": "The tag's color.",
                    "enum": [
                      "blue",
                      "amber",
                      "violet",
                      "cyan",
                      "emerald",
                      "rose",
                      "teal",
                      "orange",
                      "pink",
                      "indigo",
                      "lime",
                      "slate"
                    ]
                  },
                  "update_automations": {
                    "type": "boolean",
                    "description": "Default true: automations that name the tag follow the rename."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Roof replacement",
                "color": "amber"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "tag-uuid",
                    "name": "Roof replacement",
                    "color": "amber",
                    "automations_updated": 2
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_tag",
        "tags": [
          "CRM leads"
        ],
        "summary": "Delete a tag",
        "description": "Takes the tag off every contact for good. Automations that name it are left as they are.\n\nWho can call it: Owners and admins.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag_id",
            "in": "path",
            "required": true,
            "description": "The tag (GET /v1/tags).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "tag-uuid",
                    "deleted": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tags/merge": {
      "post": {
        "operationId": "merge_tags",
        "tags": [
          "CRM leads"
        ],
        "summary": "Merge tags into one",
        "description": "Folds tags into the one you keep: their contacts get the kept tag and the others are deleted.\n\n- Moving a tag is not adding it, so no \"Tag added\" automation starts.\n- Automations that name a folded-in tag are rewritten to the kept one unless `update_automations` is false.\n- Name tags by name or id.\n\nWho can call it: Owners and admins.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The tags to fold in (names or ids, up to 50)."
                  },
                  "into": {
                    "type": "string",
                    "description": "The tag to keep (name or id)."
                  },
                  "update_automations": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "required": [
                  "workspace_id",
                  "tags",
                  "into"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "tags": [
                  "roof",
                  "Roofing lead"
                ],
                "into": "Roofing"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "kept": {
                      "id": "tag-uuid",
                      "name": "Roofing"
                    },
                    "merged": [
                      {
                        "id": "uuid",
                        "name": "roof"
                      },
                      {
                        "id": "uuid",
                        "name": "Roofing lead"
                      }
                    ],
                    "contacts_moved": 41,
                    "automations_updated": 1
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "operationId": "send_message",
        "tags": [
          "Messaging"
        ],
        "summary": "Send an SMS, email, Instagram or Messenger message",
        "description": "Sends from the sub-account's own number / verified sending domain and logs the message on the lead timeline.\n\n- Email requires a subject.\n- Address the message with `lead_id`, or with a raw `to` (E.164 phone for SMS, email address for email) plus `workspace_id` — Local Flywheel matches an existing contact or creates one.\n- Every send counts against the daily unique-contact safety limit (300 contacts per UTC day by default); replies to contacts already messaged today are free of the cap.\n- Over the cap the call answers 429.\n- Each message is billed at the platform rate and counts against the key's monthly credit budget, if it has one (402 when the budget is used up); a text through one of the sub-account's iMessage Macs is free.\n- A text or email (and an email's subject) can use the lead's variables, as in the Inbox and automations: `{first_name}`, `{full_name}`, `{business_name}` and the rest listed by `GET /v1/workspace-automations/reference` are filled in for the lead before it goes.\n- The message is sent as the key's user, as from the Inbox: the conversation names them, the Activity Log records them, the numbers and Macs they may text from apply, and an archived conversation comes back to the Inbox.\n\nWith `send_at` the message is scheduled instead, exactly like the Inbox's \"Schedule message\": the call answers 201 with the scheduled message, and at that time it is sent from the lead's usual number or sender as the key's user, with the same opt-out, credit and limit checks as a send now (a refusal then marks it failed with the reason).\n\n- A contact who opted out, or has no phone or email for the channel, is refused up front (400).\n- A scheduled message counts against the key's credit budget when it is scheduled.\n- See, change, cancel or send it early with `/v1/scheduled-messages`.\n\nWith `channel` instagram or messenger the message is a reply in the Instagram or Messenger conversation the lead started with the business (`lead_id` only), exactly like replying from the Inbox: text only (Instagram up to 1,000 characters, Messenger 2,000), sent now, through the connected account the lead wrote to last, as the key's user.\n\n- Instagram and Messenger only allow it within 24 hours of the person's last message there: after that the call answers 409 `window_closed` with `reply_window_ends_at`; also 409 when the lead never messaged there (`no_social_contact`) or the account is switched off or needs connecting again (`channel_disabled`, `needs_reconnect`), and 403 `not_enabled` when Instagram & Messenger is off for the account.\n- It is free, uses none of the credit budget (still refused once the budget is used up) and isn't counted in the daily contact limit.\n- The answer carries `message_id` and `account_id` (`GET /v1/social/accounts`).\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lead_id": {
                    "type": "string",
                    "description": "Lead to message. Required for instagram and messenger."
                  },
                  "to": {
                    "type": "string",
                    "description": "Without lead_id: raw destination (E.164 phone for sms, email address for email; requires workspace_id). With lead_id, sms only: which of the lead's numbers to text (phone or one of extra_phones); leave out for the main number."
                  },
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id. Required when using `to` (omit on pinned keys)."
                  },
                  "channel": {
                    "type": "string",
                    "description": "sms, email, instagram or messenger.",
                    "enum": [
                      "sms",
                      "email",
                      "instagram",
                      "messenger"
                    ]
                  },
                  "body": {
                    "type": "string",
                    "description": "Message text."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Required for email."
                  },
                  "name": {
                    "type": "string",
                    "description": "Contact name used when `to` creates a new lead."
                  },
                  "media_urls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 10 MMS/attachment URLs."
                  },
                  "actor_label": {
                    "type": "string",
                    "description": "Sender label shown in the timeline."
                  },
                  "send_at": {
                    "type": "string",
                    "description": "Schedule instead of sending now: ISO 8601 with a time zone (Z or an offset), e.g. 2026-10-20T09:00:00-05:00. In the future and at most 365 days ahead. Answers 201 with `scheduled_message`."
                  },
                  "send_as": {
                    "type": "string",
                    "description": "Texts, with an iMessage Mac connected (Beta): imessage sends a blue iMessage from one of the sub-account's iPhone numbers, sms from its business number, auto (default) lets the routing choose. The answer's `transport` says how it went (imessage, or mac_sms for the iPhone's own SMS).",
                    "enum": [
                      "auto",
                      "imessage",
                      "sms"
                    ]
                  },
                  "imessage_line_id": {
                    "type": "string",
                    "description": "Texts: which Mac (iPhone number) sends it (GET /v1/imessage/lines)."
                  },
                  "audio_message": {
                    "type": "boolean",
                    "description": "Texts: the one media_urls file is a voice message. Through a Mac running Advanced mode it arrives as a real iMessage audio message; anywhere else as an audio attachment. Not with send_at."
                  }
                },
                "required": [
                  "channel",
                  "body"
                ],
                "additionalProperties": true
              },
              "example": {
                "lead_id": "uuid",
                "channel": "sms",
                "body": "Hi Jane, are you still looking for a quote?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "list_messages",
        "tags": [
          "Messaging"
        ],
        "summary": "List recent messages on this sub-account",
        "description": "Every SMS and email on the sub-account's Local Flywheel numbers and inboxes, and every Instagram and Messenger DM, newest first.\n\n- A DM has `channel` instagram or messenger, no from / to / subject, its pictures and files in `media_urls` and `social` { `account_id`: the connected account (`GET /v1/social/accounts`), `sent_by`: user, ai, automation or page (sent from the Instagram or Facebook apps) on the business's side }.\n- For polling, pass `cursor` (or `since`) — results then come oldest-first and `next_cursor` walks forward with no duplicates and no missed messages.\n- Poll no more than once every 10 seconds, or subscribe to the `message.received` webhook instead.\n- A text that went through one of the sub-account's iMessage Macs carries `transport` (imessage, or `mac_sms` for the iPhone's own green text) and `imessage` `{ line_id, from, service: imessage | sms | rcs, delivered_at, read_at }`; a tapback carries `reaction` `{ by: them | you, type, emoji, reacts_to: the message it hangs on, removed }`.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on pinned keys).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "Only messages with this contact.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "sms, email, instagram or messenger.",
            "schema": {
              "type": "string",
              "enum": [
                "sms",
                "email",
                "instagram",
                "messenger"
              ]
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "inbound or outbound.",
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO-8601 timestamp; returns messages created after it, oldest-first.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`next_cursor` from the previous poll.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Default 50, max 200.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/scheduled-messages": {
      "get": {
        "operationId": "list_scheduled_messages",
        "tags": [
          "Messaging"
        ],
        "summary": "List scheduled texts and emails",
        "description": "Messages waiting to be sent later, scheduled in the Inbox or with `POST /v1/messages` and `send_at`.\n\n- By default the upcoming ones (pending, sending, failed), soonest first, like the dashed bubbles at the end of a conversation; `status` = sent, cancelled or all lists history, newest first.\n- A failed message carries `last_error`.\n- Viewers limited to their own leads only see those leads' messages.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "Only this lead's messages.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Default upcoming (pending, sending, failed).",
            "schema": {
              "type": "string",
              "enum": [
                "upcoming",
                "pending",
                "sending",
                "failed",
                "sent",
                "cancelled",
                "all"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "scheduled_messages": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "lead_id": "uuid",
                        "channel": "sms",
                        "body": "Hi Jane, just checking in about your quote.",
                        "subject": null,
                        "from_number": null,
                        "from_sender_id": null,
                        "media_urls": [],
                        "attachment_urls": [],
                        "attachment_names": [],
                        "scheduled_at": "2026-10-20T14:00:00+00:00",
                        "status": "pending",
                        "attempts": 0,
                        "last_error": null,
                        "sent_at": null,
                        "lead_event_id": null,
                        "created_by": "uuid",
                        "cancelled_at": null,
                        "cancelled_by": null,
                        "created_at": "2026-10-16T18:02:11Z",
                        "updated_at": "2026-10-16T18:02:11Z",
                        "lead": {
                          "id": "uuid",
                          "full_name": "Jane Doe",
                          "phone": "+14155550123",
                          "email": null
                        }
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/scheduled-messages/{scheduled_message_id}": {
      "patch": {
        "operationId": "update_scheduled_message",
        "tags": [
          "Messaging"
        ],
        "summary": "Change, cancel or restore a scheduled message",
        "description": "Like the Inbox's Edit, Cancel and Undo. Send any of body, subject (emails), `scheduled_at` and `media_urls` (texts) to change a pending or failed message: it goes back in the queue (status pending).\n\n- `status: \"cancelled\"` (on its own) stops it; `status: \"pending\"` brings a cancelled one back (send a new `scheduled_at` when its time has passed).\n- 409 when it is sending or already sent.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scheduled_message_id",
            "in": "path",
            "required": true,
            "description": "Scheduled message id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The new text."
                  },
                  "subject": {
                    "type": "string",
                    "description": "The new subject (emails only)."
                  },
                  "scheduled_at": {
                    "type": "string",
                    "description": "ISO 8601 with a time zone, in the future and at most 365 days ahead."
                  },
                  "media_urls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Picture URLs for a text, max 10 (replaces the list)."
                  },
                  "status": {
                    "type": "string",
                    "description": "cancelled to cancel, pending to restore.",
                    "enum": [
                      "pending",
                      "cancelled"
                    ]
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "scheduled_at": "2026-10-21T09:00:00-05:00",
                "body": "Hi Jane, following up on your quote. Any questions?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "scheduled_message": {
                      "id": "uuid",
                      "channel": "sms",
                      "body": "Hi Jane, following up on your quote. Any questions?",
                      "scheduled_at": "2026-10-21T14:00:00+00:00",
                      "status": "pending"
                    },
                    "changed": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/scheduled-messages/{scheduled_message_id}/send-now": {
      "post": {
        "operationId": "send_scheduled_message_now",
        "tags": [
          "Messaging"
        ],
        "summary": "Send a scheduled message now",
        "description": "The Inbox's \"Send now\": a pending or failed message goes out at once, as the teammate who scheduled it, with the usual opt-out, credit and limit checks, and is billed like any text or email.\n\n- 200 = sent; 202 = a sending hiccup, it tries again by itself in a couple of minutes; 400 = refused, with the reason (the message is marked failed); 409 = cancelled, already sending or sent.\n- Refused when the key's credit budget is used up.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `messaging:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scheduled_message_id",
            "in": "path",
            "required": true,
            "description": "Scheduled message id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sent": true,
                    "scheduled_message": {
                      "id": "uuid",
                      "status": "sent",
                      "sent_at": "2026-10-16T18:05:02Z",
                      "lead_event_id": "uuid"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/messages/{message_id}": {
      "get": {
        "operationId": "get_message",
        "tags": [
          "Messaging"
        ],
        "summary": "Read one message",
        "description": "Required scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "description": "Message id from GET /v1/messages.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/messages/limits": {
      "get": {
        "operationId": "message_limits",
        "tags": [
          "Messaging"
        ],
        "summary": "Check today's contact-safety limits",
        "description": "Returns the daily unique-contact cap (default 300 per UTC day), how many contacts have been used, what's left, segment usage and the reset time. The same values ride on every messaging call as X-Contacts-Limit / -Used / -Remaining / -Reset headers.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on pinned keys).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/conversation": {
      "get": {
        "operationId": "lead_conversation",
        "tags": [
          "Messaging"
        ],
        "summary": "Read the conversation with a lead",
        "description": "Texts, emails, Instagram and Messenger DMs, website chat, calls, voicemails and notes, newest first.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Default 50.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/imessage/lines": {
      "get": {
        "operationId": "list_imessage_lines",
        "tags": [
          "Messaging"
        ],
        "summary": "List the sub-account's iMessage Macs",
        "description": "Every Mac connected to the sub-account for iMessage, the default first: its iPhone number, whose Mac it is, whether it's online, what the Mac reports about itself (`health`: Messages signed in, Full Disk Access, awake, lid closed allowed, iCloud still syncing, the number missing from or switched off in Messages), whether Advanced mode runs on it (`advanced_mode`: real audio messages and reactions), its settings (scope, `create_leads`, `new_conversations`, fallback, `offline_minutes`, `ai_replies`), who can text from it (access, `allowed_user_ids`, and `can_use` for you), its limits (new conversations a day and an hour, tries and length before someone first replies) and today's usage (new conversations today and this hour, messages waiting, every text it sent today, and how many other accounts share that iPhone's limit).\n\n- `has_number` says whether the sub-account has a business number to fall back on; without one every text goes through a Mac.\n- Connecting and disconnecting a Mac happen in the app.\n\nWho can call it: Any member.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lines": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "number": "+17145550123",
                        "handles": [
                          "+17145550123"
                        ],
                        "label": null,
                        "device_name": "Front desk iMac",
                        "owner": {
                          "user_id": "uuid",
                          "name": "Pat Owner"
                        },
                        "is_default": true,
                        "online": true,
                        "last_seen_at": "2026-10-23T15:32:02Z",
                        "connected_at": "2026-10-01T16:00:00Z",
                        "app_version": "0.6.3",
                        "macos_version": "15.6",
                        "advanced_mode": false,
                        "health": {
                          "messages_running": true,
                          "signed_in": true,
                          "full_disk_access": true,
                          "automation": true,
                          "awake": true,
                          "login_item": true,
                          "laptop": false,
                          "lid_closed_ok": null,
                          "on_battery": false,
                          "icloud_syncing": false,
                          "has_number": true,
                          "number_off": false,
                          "advanced": false,
                          "advanced_ready": false
                        },
                        "settings": {
                          "scope": "crm",
                          "create_leads": true,
                          "new_conversations": "sms",
                          "fallback": "mac_then_number",
                          "offline_minutes": 10,
                          "ai_replies": true
                        },
                        "access": "everyone",
                        "allowed_user_ids": [],
                        "can_use": true,
                        "can_manage": true,
                        "limits": {
                          "new_per_day": 50,
                          "new_per_hour": 6,
                          "first_contact_messages": 5,
                          "first_contact_chars": 300
                        },
                        "usage": {
                          "new_today": 12,
                          "new_this_hour": 2,
                          "waiting": 0,
                          "shared_with": 0,
                          "messages_today": 41
                        }
                      }
                    ],
                    "has_number": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/imessage/lines/{line_id}": {
      "patch": {
        "operationId": "update_imessage_line",
        "tags": [
          "Messaging"
        ],
        "summary": "Change an iMessage Mac's settings",
        "description": "Send only what changes. The sub-account's owners and admins change any Mac; everyone else only their own; only owners and admins choose the default (`is_default`: true moves it from the old one).\n\naccess: everyone, owner (only the person whose Mac it is) or selected (`allowed_user_ids`); owners, admins and the Mac's owner can always text from it, and AI replies and automations aren't limited.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "line_id",
            "in": "path",
            "required": true,
            "description": "The Mac (GET /v1/imessage/lines).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "A name for it (max 80), or null."
                  },
                  "is_default": {
                    "type": "boolean",
                    "description": "true makes it the default Mac."
                  },
                  "access": {
                    "type": "string",
                    "description": "Who can text from it by hand.",
                    "enum": [
                      "everyone",
                      "owner",
                      "selected"
                    ]
                  },
                  "allowed_user_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "With access selected: the team members who can."
                  },
                  "scope": {
                    "type": "string",
                    "description": "crm: only conversations with people already in the CRM sync; all: every one-to-one conversation.",
                    "enum": [
                      "crm",
                      "all"
                    ]
                  },
                  "create_leads": {
                    "type": "boolean",
                    "description": "With scope all: someone new who texts in becomes a lead."
                  },
                  "new_conversations": {
                    "type": "string",
                    "description": "How a first text to someone goes.",
                    "enum": [
                      "sms",
                      "imessage"
                    ]
                  },
                  "fallback": {
                    "type": "string",
                    "description": "When they aren't on iMessage or the Mac is offline: the business number, RCS or SMS from the iPhone through the Mac, the iPhone and then the business number (mac_then_number, the default), or nothing.",
                    "enum": [
                      "number",
                      "mac",
                      "mac_then_number",
                      "none"
                    ]
                  },
                  "offline_minutes": {
                    "type": "number",
                    "description": "How long a message waits for an offline Mac before the fallback, 2-240."
                  },
                  "ai_replies": {
                    "type": "boolean",
                    "description": "The AI texter may answer iMessages."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "access": "selected",
                "allowed_user_ids": [
                  "uuid"
                ],
                "new_conversations": "imessage"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "line": {
                      "id": "uuid",
                      "number": "+17145550123",
                      "access": "selected",
                      "allowed_user_ids": [
                        "uuid"
                      ],
                      "settings": {
                        "new_conversations": "imessage"
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/messages/{message_id}/reaction": {
      "post": {
        "operationId": "react_to_message",
        "tags": [
          "Messaging"
        ],
        "summary": "React to an iMessage (tapback)",
        "description": "Puts a tapback (❤️ 👍 👎 😂 ‼️ ❓) on a text that went through one of the sub-account's Macs, like the Inbox's reaction picker; `remove: true` takes yours back.\n\n- Only a Mac running Advanced mode can (`advanced_mode` on `GET /v1/imessage/lines`): otherwise 409 `advanced_off`.\n- The reaction is queued (202) and shows on the message (its `reaction`, by you) once the Mac has sent it; if it can't, a note says why on the conversation.\n- Anyone who can see the lead and text from that number.\n- Free, like every text through a Mac.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "description": "The text to react to (an id from GET /v1/messages or the lead's conversation).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reaction": {
                    "type": "string",
                    "description": "love, like, dislike, laugh, emphasize or question (or the emoji).",
                    "enum": [
                      "love",
                      "like",
                      "dislike",
                      "laugh",
                      "emphasize",
                      "question"
                    ]
                  },
                  "remove": {
                    "type": "boolean",
                    "description": "true takes your reaction back."
                  }
                },
                "required": [
                  "reaction"
                ],
                "additionalProperties": true
              },
              "example": {
                "reaction": "love"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "queued": true,
                    "job_id": "uuid",
                    "message_id": "uuid",
                    "reaction": "love",
                    "remove": false,
                    "line_id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/imessage/automated-texts": {
      "put": {
        "operationId": "set_automated_texts_from",
        "tags": [
          "Messaging"
        ],
        "summary": "Choose who automated texts send from",
        "description": "Settings > Phone's \"Automated texts send from\" (also on the Automations page): the way the texts the sub-account sends on its own go once it has a Mac connected.\n\n- Automations, appointment confirmations and reminders, follow-ups and first texts follow it; an AI reply to a customer's own text still answers the way they wrote, and a step or send that names its own way keeps it.\n- automatic lets each iPhone's iMessage settings decide, number sends from the business number, a `line_id` from that iPhone.\n- `GET /v1/imessage/lines` returns the current choice as `automated_texts_send_from`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "send_from": {
                    "type": "string",
                    "description": "automatic, number, or the line_id of a connected iPhone (GET /v1/imessage/lines)."
                  }
                },
                "required": [
                  "workspace_id",
                  "send_from"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "send_from": "number"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "automated_texts_send_from": "number"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/social/accounts": {
      "get": {
        "operationId": "list_social_accounts",
        "tags": [
          "Messaging"
        ],
        "summary": "List the connected Instagram and Messenger accounts",
        "description": "The Instagram accounts and Facebook Pages (Messenger) connected in Settings > Instagram & Messenger: whether its DMs come into the Inbox (`enabled`; comment rules run either way), whether the AI answers its DMs (`ai_replies`), its connection (`status` connected, `needs_reconnect` or error, with `last_error`) and `live`: replies can go out through it.\n\n- Connecting and switching accounts happen in the app.\n- 403 `not_enabled` when Instagram & Messenger is off for the account.\n\nWho can call it: Any member.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "accounts": [
                      {
                        "id": "uuid",
                        "platform": "instagram",
                        "name": "@acmeroofing",
                        "page_name": "Acme Roofing",
                        "username": "acmeroofing",
                        "enabled": true,
                        "ai_replies": true,
                        "status": "connected",
                        "live": true,
                        "last_error": null,
                        "last_event_at": "2026-10-28T19:02:11Z",
                        "connected_at": "2026-10-01T16:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/social/comments": {
      "get": {
        "operationId": "list_social_comments",
        "tags": [
          "Messaging"
        ],
        "summary": "Instagram and Facebook comments the comment-to-DM rules saw",
        "description": "Recent comments in Settings > Instagram & Messenger: every comment a comment-to-DM rule matched, newest first, with the post, who wrote it, the rule, whether a public reply went under it, what happened to the DM (`dm_status` sent, failed with `error`, or skipped: that person already got it) and the lead it started a conversation with.\n\n- `counts` has the number per result with every other filter applied; page with `offset` (`next_offset`).\n- To answer someone, reply in their conversation with `POST /v1/messages` (channel instagram or messenger).\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "What happened to the DM.",
            "schema": {
              "type": "string",
              "enum": [
                "sent",
                "failed",
                "skipped"
              ]
            }
          },
          {
            "name": "account_id",
            "in": "query",
            "required": false,
            "description": "One connected account (GET /v1/social/accounts).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "rule_id",
            "in": "query",
            "required": false,
            "description": "One comment-to-DM rule.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "post_id",
            "in": "query",
            "required": false,
            "description": "One post or reel.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commenter_id",
            "in": "query",
            "required": false,
            "description": "Everything from one person (commenter.id).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Commenter name or comment text contains (max 100).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO date or time, comments on or after.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO date or time, comments on or before.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "oldest_first",
            "in": "query",
            "required": false,
            "description": "Default false (newest first).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "next_offset from the previous page.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "comments": [
                      {
                        "id": "uuid",
                        "platform": "instagram",
                        "account": {
                          "id": "uuid",
                          "name": "@acmeroofing"
                        },
                        "comment_id": "17890000000000000",
                        "post_id": "17840000000000000",
                        "commenter": {
                          "id": "17841400000000000",
                          "name": "jane.doe"
                        },
                        "text": "PRICE",
                        "rule": {
                          "id": "uuid",
                          "name": "Price keyword"
                        },
                        "public_reply": true,
                        "dm_status": "sent",
                        "error": null,
                        "lead_id": "uuid",
                        "created_at": "2026-10-28T19:02:11Z"
                      }
                    ],
                    "counts": {
                      "all": 142,
                      "sent": 131,
                      "failed": 4,
                      "skipped": 7
                    },
                    "has_more": true,
                    "next_offset": 25
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/social/settings": {
      "get": {
        "operationId": "get_social_settings",
        "tags": [
          "Messaging"
        ],
        "summary": "Who goes into Leads from Instagram and Messenger",
        "description": "Settings > Instagram & Messenger > Who goes into Leads.\n\n- `lead_mode` qualified (the default): someone who only sent a DM is a conversation in Messages, not a lead, until they share a phone number or email, book, or someone adds them to Leads (leads carry `chat_only` meanwhile and every lead count leaves them out).\n- everyone: every new DM person is a lead right away.\n- `dm_leads_to_move` (owners and admins; null for others): how many Instagram and Messenger people from before are still in Leads as New with no phone, email, booking or deal (`POST /v1/social/move-dm-leads` moves them).\n- 403 `not_enabled` when Instagram & Messenger is off for the account.\n\nWho can call it: Any member reads the mode.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "lead_mode": "qualified",
                    "dm_leads_to_move": 12
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_social_settings",
        "tags": [
          "Messaging"
        ],
        "summary": "Change who goes into Leads from Instagram and Messenger",
        "description": "qualified: only people who share a phone number or email, book, or are added by someone become leads (the rest stay conversations in Messages).\n\n- everyone: every new DM person is a lead (and starts new-lead automations, webhooks and the field-service push like any new lead).\n- Applies to people who message from now on; `POST /v1/social/move-dm-leads` tidies up the ones from before.\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "lead_mode": {
                    "type": "string",
                    "description": "qualified or everyone.",
                    "enum": [
                      "qualified",
                      "everyone"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "lead_mode"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_mode": "qualified"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "lead_mode": "qualified"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/social/move-dm-leads": {
      "post": {
        "operationId": "move_dm_leads",
        "tags": [
          "Messaging"
        ],
        "summary": "Move Instagram and Messenger people back to Messages",
        "description": "The settings' \"Move them to Messages\": Instagram and Messenger people who became New leads before (or while `lead_mode` was everyone) and never did anything a lead does (still New, no phone or email, no booking, deal or value, nobody added them to Leads) become conversations again.\n\n- Silent: no automations, webhooks or field-service push; their conversations stay in Messages.\n- apply false (the default) only counts them (`would_move`); apply true moves them (`moved`).\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "apply": {
                    "type": "boolean",
                    "description": "true moves them; false (default) only counts."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "apply": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "moved": 12
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendars": {
      "get": {
        "operationId": "list_calendars",
        "tags": [
          "Bookings"
        ],
        "summary": "List booking calendars",
        "description": "Every setting POST / `PATCH /v1/calendars` takes, read the way the booking page reads it: hours, length, buffers, hosts' mode, texts, pricing (with each option's and add-on's id, used by availability and bookings), design, `duration_days` (full-day jobs), `schedule_group` (shared schedule), fields and questions (the booking form), `image_url`, the payment settings, a summary (`price_from_cents`, `price_to_cents`, `length_label` such as \"4-6 hr\", `has_options`, `takes_payment`) and `booking_path` (/c/<slug>).\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "calendars": [
                      {
                        "id": "uuid",
                        "slug": "triple-t-interior-exterior",
                        "name": "Triple T Interior + Exterior",
                        "title": "Triple T Interior + Exterior",
                        "duration_minutes": 240,
                        "duration_days": null,
                        "schedule_group": "Main crew",
                        "assignment_mode": "unassigned",
                        "slots_per_window": 1,
                        "max_days_ahead": 120,
                        "pricing": {
                          "enabled": true,
                          "show_prices": true,
                          "price_cents": null,
                          "price_note": null,
                          "options_label": "Vehicle size",
                          "options": [
                            {
                              "id": "opt-car",
                              "name": "Car",
                              "description": null,
                              "price_cents": 31500,
                              "duration_minutes": 240,
                              "duration_days": null,
                              "image_url": null
                            },
                            {
                              "id": "opt-van",
                              "name": "Van",
                              "description": null,
                              "price_cents": 53500,
                              "duration_minutes": 360,
                              "duration_days": null,
                              "image_url": null
                            }
                          ],
                          "addons_label": "Add-ons",
                          "addons": [
                            {
                              "id": "add-pet",
                              "name": "Pet hair",
                              "description": null,
                              "price_cents": 4000,
                              "extra_minutes": 30,
                              "image_url": null
                            }
                          ],
                          "deposit": {
                            "mode": "fixed",
                            "amount_cents": 5000,
                            "percent": 25
                          }
                        },
                        "design": null,
                        "questions": [
                          {
                            "key": "vehicle",
                            "label": "Vehicle year / make / model",
                            "field_type": "text",
                            "options": [],
                            "required": true,
                            "enabled": true,
                            "save_to_crm": true,
                            "placeholder": null,
                            "helper_text": null
                          }
                        ],
                        "summary": {
                          "price_from_cents": 31500,
                          "price_to_cents": 53500,
                          "length_label": "4-6 hr",
                          "has_options": true,
                          "takes_payment": true
                        },
                        "booking_path": "/c/triple-t-interior-exterior",
                        "is_active": true
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_calendar",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Create a booking calendar",
        "description": "A new calendar has no host unless `host_user_id` or hosts is sent. Hosts must be members of the sub-account (`GET /v1/members`).\n\n- The response is the calendar as `GET /v1/calendars` shows it, with its public booking path (/c/<slug>).\n- Calendars are switched off with `is_active`=false rather than deleted.\n- The booking page can show prices with options and add-ons and take a deposit (pricing), have its own look (design), book whole working days (`duration_days`), share one schedule with other calendars (`schedule_group`) and ask its own questions (questions).\n- Taking money at booking needs Stripe, Authorize.net or Whop connected to the sub-account in the app first.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Calendar name (max 80)."
                  },
                  "title": {
                    "type": "string",
                    "description": "Shown to the person booking."
                  },
                  "duration_minutes": {
                    "type": "number",
                    "description": "5-1440, default 30."
                  },
                  "buffer_minutes": {
                    "type": "number",
                    "description": "0-1440, default 0. Always saved as 0 on an arrival_window calendar (a window books the whole window and pads nothing), as in the app."
                  },
                  "min_notice_minutes": {
                    "type": "number",
                    "description": "Default 60."
                  },
                  "max_days_ahead": {
                    "type": "number",
                    "description": "1-365, default 14."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA zone, e.g. America/Chicago. Defaults to the sub-account's."
                  },
                  "weekly_hours": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Per day, 24h HH:MM windows: {\"mon\":[[\"09:00\",\"17:00\"]],\"sat\":[]}. Default Mon-Fri 9-5."
                  },
                  "date_overrides": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Days off or special hours: [{\"date\":\"2026-12-25\",\"pairs\":[]}]."
                  },
                  "assignment_mode": {
                    "type": "string",
                    "description": "Who takes the booking. Default unassigned (no host), or single when host_user_id is sent.",
                    "enum": [
                      "single",
                      "round_robin",
                      "collective",
                      "unassigned"
                    ]
                  },
                  "host_user_id": {
                    "type": "string",
                    "description": "Host of a single-host calendar (required for single)."
                  },
                  "hosts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "User ids sharing a round_robin / collective calendar."
                  },
                  "meeting_type": {
                    "type": "string",
                    "description": "Default phone. in_person: the customer comes to meeting_location (studio, shop, office). customer_address: the team goes to the customer's home, and the booking page asks for their address.",
                    "enum": [
                      "zoom",
                      "google_meet",
                      "phone",
                      "phone_attendee",
                      "in_person",
                      "customer_address",
                      "custom"
                    ]
                  },
                  "scheduling_mode": {
                    "type": "string",
                    "description": "exact times, or an arrival window for trades.",
                    "enum": [
                      "exact",
                      "arrival_window"
                    ]
                  },
                  "arrival_window_minutes": {
                    "type": "number",
                    "description": "15-720."
                  },
                  "appointment_texts": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Confirmation and reminder texts for appointments on this calendar, keyed by confirmation, reminder_24h, reminder_1h, reminder_5m. Each takes {\"mode\":\"custom\",\"template\":\"...\"} (this wording, sent even when the sub-account has that text off), {\"mode\":\"off\"} (never sent for this calendar), or null / {\"mode\":\"inherit\"} (the sub-account's text, the default). Only the texts you name change."
                  },
                  "slots_per_window": {
                    "type": "number",
                    "description": "1-50: how many jobs can run at the same moment (crews)."
                  },
                  "duration_days": {
                    "type": "number",
                    "description": "Full-day jobs, 1-14 working days: each booking runs from opening time on its first day to closing time on its last, skipping closed days. null = timed by duration_minutes."
                  },
                  "schedule_group": {
                    "type": "string",
                    "description": "Shared schedule name (max 60): calendars with the same group count each other's bookings, so one crew's time is never sold twice across services. null = its own schedule."
                  },
                  "booking_requests": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Bookings on this calendar are requests until someone confirms them, merged: {\"on\":true,\"ai_confirms\":true,\"ai_rule\":\"They own the home and will be there\",\"message\":\"We'll confirm within the hour.\"}. While on, a booking made by itself (booking page, Smart Form, the AI, this API) is saved held: the time is taken, but no confirmation, reminders or invite go out and \"Appointment requested\" automations run instead of \"Appointment booked\". The team confirms or declines it on Appointments; with ai_confirms (needs ai_rule, max 600) the AI texter may confirm it once the rule is met. message (max 300) is what the booking page says after a request. Bookings a person makes by hand and existing customers' are never requests. The API does not show the hold yet: a held request reads as status confirmed in GET /v1/bookings, and confirming or declining it is done on the Appointments page. null = off."
                  },
                  "pricing": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Prices on the booking page. Merged into what the calendar has, except options and addons, which replace their lists (send each row's id to keep it; ids come back in GET /v1/calendars). Money in cents. { enabled, show_prices, price_cents (no options), price_note (max 160), options_label (\"Vehicle size\"), options: [{ id?, name (max 80), description?, price_cents, duration_minutes (5-1440, its own job length), duration_days (full-day calendars), image_url? }] (max 24; the customer picks one), addons_label, addons: [{ id?, name, description?, price_cents, extra_minutes (0-720), image_url? }] (max 24), deposit: { mode: none | fixed | percent | full, amount_cents, percent (1-100) } }. A calendar that never had pricing switches it on unless enabled is false; null clears it. A deposit needs a connected gateway."
                  },
                  "design": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The booking page look, merged into the current design. { enabled, preset (clean, studio, showroom, midnight, clinic, fresh, warm, editorial, sunset, bold, ocean, builder, spa, lavender, mono, forest, graphite: applied first; it sets the whole look, layout included), mode: light | dark | auto, colors: { background, surface, text, button } (#rrggbb, merged), font, heading_font (\"match\" or a font), radius: sharp | soft | rounded | pill, button_style: solid | soft | outline, backdrop: solid | glow | gradient | dots | photo (the cover, needs cover_url) | image (needs background_url), layout: card | split (details beside the calendar on computers) | open (no card), header_align: left | center, logo_size: small | medium | large, day_style: tiles | strip | calendar (windows over three weeks always show the calendar), time_style: grid | list | pills, picked_style: tint | filled, shadow: none | soft | lifted, heading_case: normal | upper, logo_url, cover_url, background_url (https), hide_avatar, show_counts, group_times, labels: { pick_day (40), pick_time (40), done_title (60), done_text (240) } (\"\" = the usual words, merged), custom_css (max 12000) }. Fonts: inter, poppins, dm-sans, space-grotesk, manrope, outfit, figtree, plus-jakarta, work-sans, rubik, nunito-sans, montserrat, raleway, urbanist, sora, lexend, archivo, barlow, karla, public-sans, bricolage, bebas, anton, archivo-black, syne, clash, oswald, playfair, dm-serif, lora, libre-baskerville, cormorant, instrument-serif, fraunces, source-serif, merriweather, jetbrains-mono, space-mono, ibm-plex-mono, system. A page that never had a design switches it on unless enabled is false; null = the classic page. It carries into embeds and custom domains."
                  },
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The calendar's own booking questions, up to 30, replacing the list: [{ key?, label (max 160), field_type: text | textarea | number | money | phone | email | url | select | multiselect | boolean | date | datetime | rating | file (photos or PDFs, up to 6), options (select / multiselect: 2-40), option_style?, required?, enabled?, save_to_crm? (never for file), placeholder?, helper_text? }]. Answers show on the appointment and the lead."
                  },
                  "fields": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Contact fields on the booking form, merged: {\"address\":{\"enabled\":true,\"required\":true,\"autocomplete\":true},\"email\":{\"required\":false}}. Keys: full_name, first_name, last_name, email, phone, address, state, notes. Phone or email stays on; full_name or first_name + last_name."
                  },
                  "image_url": {
                    "type": "string",
                    "description": "The service's photo (https): on its booking page and its service menu card."
                  },
                  "currency": {
                    "type": "string",
                    "description": "Prices and payments in this currency.",
                    "enum": [
                      "usd",
                      "cad",
                      "gbp",
                      "eur",
                      "aud"
                    ]
                  },
                  "payment_gateway": {
                    "type": "string",
                    "description": "Charge through this connected gateway; null = whichever is connected (Stripe first).",
                    "enum": [
                      "stripe",
                      "authorize_net",
                      "whop"
                    ]
                  },
                  "payment_hold_minutes": {
                    "type": "number",
                    "description": "15-120: how long the time is held while they pay."
                  },
                  "payment_label": {
                    "type": "string",
                    "description": "What the checkout calls the payment, e.g. \"Deposit\" (max 60)."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Triple T Interior + Exterior",
                "duration_minutes": 240,
                "assignment_mode": "unassigned",
                "schedule_group": "Main crew",
                "max_days_ahead": 120,
                "pricing": {
                  "options_label": "Vehicle size",
                  "options": [
                    {
                      "name": "Car",
                      "price_cents": 31500,
                      "duration_minutes": 240
                    },
                    {
                      "name": "SUV",
                      "price_cents": 38500,
                      "duration_minutes": 300
                    },
                    {
                      "name": "Van",
                      "price_cents": 53500,
                      "duration_minutes": 360
                    }
                  ],
                  "addons": [
                    {
                      "name": "Pet hair",
                      "price_cents": 4000,
                      "extra_minutes": 30
                    }
                  ],
                  "deposit": {
                    "mode": "fixed",
                    "amount_cents": 5000
                  }
                },
                "design": {
                  "preset": "showroom"
                },
                "questions": [
                  {
                    "label": "Vehicle year / make / model",
                    "field_type": "text",
                    "required": true
                  },
                  {
                    "label": "Photos of the vehicle",
                    "field_type": "file"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendars/{calendar_id}/availability": {
      "get": {
        "operationId": "calendar_availability",
        "tags": [
          "Bookings"
        ],
        "summary": "Get open appointment slots",
        "description": "The times the calendar's booking page offers, worked out the same way: weekly hours and days off, the job length, buffers, capacity (`slots_per_window` jobs at one moment), calendars sharing its schedule, max per day, minimum notice, the booking window (`max_days_ahead`, up to a year) and the hosts' own calendars.\n\n- A calendar with options times each one differently, so send `option_id` (400 lists the options otherwise) and any `addon_ids`; the answer carries a quote (option, add-ons, length, total, deposit, balance).\n- Full-day calendars also return `slot_ends` (when each start's job is done).\n- Always call this before creating a booking.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "calendar_id",
            "in": "path",
            "required": true,
            "description": "Calendar id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "A date (2026-11-03) or an ISO time; defaults to today.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "1-42, default 7.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "option_id",
            "in": "query",
            "required": false,
            "description": "The option picked (its id in GET /v1/calendars pricing.options). Required on a calendar with options.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "addon_ids",
            "in": "query",
            "required": false,
            "description": "Add-on ids, comma-separated: they add their time to the job.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "calendar": {
                      "id": "uuid",
                      "name": "Triple T Interior + Exterior",
                      "timezone": "America/Chicago",
                      "duration_minutes": 390,
                      "duration_days": null,
                      "booking_window_days": 120
                    },
                    "from": "2026-11-03T06:00:00.000Z",
                    "to": "2026-11-10T06:00:00.000Z",
                    "from_date": "2026-11-03",
                    "to_date": "2026-11-10",
                    "slots": [
                      "2026-11-03T14:00:00.000Z"
                    ],
                    "days": [
                      {
                        "date": "2026-11-03",
                        "label": "Tue, Nov 3",
                        "slots": [
                          "2026-11-03T14:00:00.000Z"
                        ]
                      }
                    ],
                    "quote": {
                      "option": {
                        "id": "opt-van",
                        "name": "Van"
                      },
                      "addons": [
                        {
                          "id": "add-pet",
                          "name": "Pet hair"
                        }
                      ],
                      "duration_minutes": 390,
                      "duration_days": null,
                      "length_label": "6 hr 30 min",
                      "total_cents": 57500,
                      "deposit_cents": 5000,
                      "balance_cents": 52500,
                      "currency": "usd",
                      "lines": [
                        {
                          "label": "Van",
                          "cents": 53500,
                          "kind": "option"
                        },
                        {
                          "label": "Pet hair",
                          "cents": 4000,
                          "kind": "addon"
                        }
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/bookings": {
      "get": {
        "operationId": "list_bookings",
        "tags": [
          "Bookings"
        ],
        "summary": "List appointments",
        "description": "Soonest first.\n\n- Each appointment has the same fields as everywhere else in the API: id, `lead_id`, `calendar_id`, `appointment_number` (the sub-account's #1001 and up, as the calendar shows it), title, `starts_at`, `ends_at`, timezone, `lead_timezone`, location, notes, `meeting_type`, `meeting_location`, `meeting_url`, `host_user_id`, status, source, `notify_lead`, `is_arrival_window` (booked as an arrival window: `starts_at` to `ends_at` is the window), `service_details` (on a priced calendar: the service, option, add-ons, length, `total_cents`, `deposit_cents`, `balance_cents` and currency; null otherwise), `created_at` and `updated_at`.\n- For owners and admins each also carries `manage_url`: the customer's own page for it (the `{reschedule_link}` of reminders, on the sub-account's CRM address), where they move or cancel it themselves; add ?cancel=1 to open on cancelling.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO start.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO end.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "Filter by lead.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "bookings": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "lead_id": "uuid",
                        "calendar_id": "uuid",
                        "title": "Estimate",
                        "starts_at": "2026-09-04T17:00:00Z",
                        "ends_at": "2026-09-04T19:00:00Z",
                        "timezone": "America/Chicago",
                        "lead_timezone": "America/Chicago",
                        "location": "12 Main St",
                        "notes": null,
                        "meeting_type": "in_person",
                        "meeting_location": null,
                        "meeting_url": null,
                        "host_user_id": "uuid",
                        "status": "scheduled",
                        "source": "api",
                        "notify_lead": true,
                        "is_arrival_window": true,
                        "service_details": null,
                        "manage_url": "https://crm.acmeroofing.com/a/3f9c2a7d1b8e4c6fa0d5e9b7c1a2f4e6",
                        "created_at": "2026-09-01T15:00:00Z",
                        "updated_at": "2026-09-01T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_booking",
        "tags": [
          "Bookings"
        ],
        "summary": "Book an appointment",
        "description": "With a calendar, the slot's capacity is checked, calendars sharing its schedule included (409 with code `slot_full`; pick a time from `GET /v1/calendars/{calendar_id}/availability`, or send force: true) and the host is picked by the calendar's round robin.\n\nBooks like the app:\n- rejects a second overlapping appointment for the same lead\n- `calendar_id` must be one of the sub-account's calendars (404 otherwise)\n- `ends_at` must be after `starts_at` and at most 24 hours later\n\n- On a priced calendar, `option_id` and `addon_ids` set the job's length and price: the booking's notes start with the pick and its `service_details` carry the option, add-ons, total, deposit and balance; the lead's deal value is filled when it has none (the response adds a quote; a warning says when a calendar with options was booked without one).\n- Bookings made through the API never take the deposit: to collect it, send the customer the booking link.\n- A full-day calendar's job starts at opening time and ends at closing time on its last working day (400 `not_a_start_time` otherwise, unless `ends_at` is sent).\n- By default the lead gets the confirmation and reminder texts and the calendar invite (`notify_lead`: false to skip them).\n- Fires the `appointment.booked` outbound webhooks.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id."
                  },
                  "starts_at": {
                    "type": "string",
                    "description": "ISO 8601 start time."
                  },
                  "ends_at": {
                    "type": "string",
                    "description": "ISO 8601 end time (instead of duration_minutes; at most 24 h after starts_at, 31 days on a full-day calendar)."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "Lead to book."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "One of the sub-account's calendars."
                  },
                  "option_id": {
                    "type": "string",
                    "description": "The option booked (GET /v1/calendars pricing.options id), e.g. the vehicle size."
                  },
                  "addon_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Add-ons booked (pricing.addons ids)."
                  },
                  "duration_minutes": {
                    "type": "number",
                    "description": "5-1440. Default: the option's length with its add-ons, else the calendar's, else 30."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA timezone."
                  },
                  "location": {
                    "type": "string",
                    "description": "Meeting location."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Internal notes."
                  },
                  "notify_lead": {
                    "type": "boolean",
                    "description": "Default true: the lead gets the confirmation email with its calendar invite plus the confirmation and reminder texts. false books quietly, and later updates or cancels stay quiet too; the host still gets the booking alert."
                  },
                  "force": {
                    "type": "boolean",
                    "description": "Skip the calendar's capacity check (the database still never double-books a person or a full calendar)."
                  }
                },
                "required": [
                  "workspace_id",
                  "starts_at"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_id": "uuid",
                "calendar_id": "uuid",
                "starts_at": "2026-11-03T14:00:00Z",
                "option_id": "opt-van",
                "addon_ids": [
                  "add-pet"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/appointment-emails": {
      "get": {
        "operationId": "get_appointment_emails",
        "tags": [
          "Bookings"
        ],
        "summary": "The appointment emails leads get",
        "description": "The emails a lead gets when they book (confirmed), when the appointment moves (updated) and when it's cancelled, each with the calendar invite attached (Settings > Messaging > Appointment Reminders > Confirmation email).\n\n- `enabled` false: leads get none (the team still gets its booking alert); `language` of our emails (en or es).\n- For each kind `sends` says whether ours or the business's own HTML goes out, with its subject (`default_subject` when empty) and HTML.\n- `variables` lists what the subject and HTML can use.\n\nWho can call it: Owners and admins.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "enabled": true,
                    "language": "en",
                    "emails": [
                      {
                        "kind": "confirmed",
                        "sends": "own",
                        "on": true,
                        "subject": "You're booked, {first_name}",
                        "default_subject": "You're booked: {appointment_title} - {when}",
                        "html": "<!DOCTYPE html><html>...</html>",
                        "html_chars": 4210
                      },
                      {
                        "kind": "updated",
                        "sends": "ours",
                        "on": false,
                        "subject": null,
                        "default_subject": "Updated: {appointment_title} - {when}",
                        "html": null,
                        "html_chars": 0
                      },
                      {
                        "kind": "cancelled",
                        "sends": "ours",
                        "on": false,
                        "subject": null,
                        "default_subject": "Cancelled: {appointment_title} - {date}",
                        "html": null,
                        "html_chars": 0
                      }
                    ],
                    "variables": [
                      "{first_name}",
                      "{when}",
                      "{reschedule_link}",
                      "{cancel_link}"
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_appointment_emails",
        "tags": [
          "Bookings"
        ],
        "summary": "Send appointment emails in the business's own HTML",
        "description": "Change any of the three (confirmed, updated, cancelled) field by field: html (the whole email, any design: a GoHighLevel or Mailchimp export works; scripts, frames, forms and javascript: links are removed), subject (up to 200 characters; empty uses the default) and on; starter: true starts from the built-in template; null puts our email back.\n\n- New HTML goes out unless on is false; a kind without HTML is ours.\n- Variables are filled for each lead, HTML-escaped: `{first_name}`, `{full_name}`, `{when}`, `{date}`, `{time}`, `{location}`, `{join_link}`, `{reschedule_link}`, `{cancel_link}`, `{appointment_title}`, `{business}`, `{business_phone}`, `{agent}`; a misspelled one stays as typed.\n- Also enabled and language.\n- The .ics invite is attached either way.\n\nWho can call it: Owners and admins.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "confirmed": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ on, subject, html } or { starter: true }; null = our email."
                  },
                  "updated": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Same, for a moved appointment."
                  },
                  "cancelled": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Same, for a cancelled one."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "false: no appointment emails to leads at all."
                  },
                  "language": {
                    "type": "string",
                    "description": "Our emails' language.",
                    "enum": [
                      "en",
                      "es"
                    ]
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "confirmed": {
                  "subject": "You're booked, {first_name}",
                  "html": "<!DOCTYPE html><html><body><p>See you {when} at {location}.</p><p><a href=\"{reschedule_link}\">Reschedule</a></p></body></html>"
                },
                "cancelled": null
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "enabled": true,
                    "language": "en",
                    "emails": [
                      {
                        "kind": "confirmed",
                        "sends": "own",
                        "on": true,
                        "subject": "You're booked, {first_name}",
                        "html_chars": 118
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/bookings/{booking_id}/reschedule": {
      "post": {
        "operationId": "reschedule_booking",
        "tags": [
          "Bookings"
        ],
        "summary": "Move an appointment",
        "description": "Re-times the reminder texts, updates the calendar mirror and the lead's invite, and fires the `appointment.rescheduled` outbound webhooks when the time changed.\n\n- The appointment keeps its length; a full-day job runs to closing time on its new last working day.\n- 409 `slot_full` when the new time is taken.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "booking_id",
            "in": "path",
            "required": true,
            "description": "Booking id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "starts_at": {
                    "type": "string",
                    "description": "New ISO start time."
                  },
                  "duration_minutes": {
                    "type": "number",
                    "description": "Optional new length, 5-1440."
                  }
                },
                "required": [
                  "starts_at"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/bookings/{booking_id}/cancel": {
      "post": {
        "operationId": "cancel_booking",
        "tags": [
          "Bookings"
        ],
        "summary": "Cancel an appointment",
        "description": "`DELETE /v1/bookings/{booking_id}` does the same.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "booking_id",
            "in": "path",
            "required": true,
            "description": "Booking id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "description": "Cancellation reason."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/bookings/{booking_id}": {
      "patch": {
        "operationId": "update_booking",
        "tags": [
          "Bookings"
        ],
        "summary": "Change an appointment's outcome, title, notes, location, host, lead notifications or lead",
        "description": "Everything but the time (use reschedule for that). status records the outcome: completed, `no_show` or cancelled release the lead from Booked and stop its reminder texts; confirmed puts it back on.\n\n- `host_user_id` must be someone on the sub-account's team (`GET /v1/members`).\n- `notify_lead`: false silences the lead's remaining reminder texts and invite updates; true turns them back on (an upcoming appointment's reminders are queued again).\n- `lead_id` links an appointment that has no lead yet (typed in by hand) to a lead of the same sub-account; one that already has a lead answers 409.\n- Linking an upcoming scheduled appointment books it for the lead like a new booking: the lead is marked booked, its follow-ups and AI calls stop, and the confirmation and reminder texts and the invite go out (unless `notify_lead` is false).\n- A past or finished appointment is only linked.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "booking_id",
            "in": "path",
            "required": true,
            "description": "Booking id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "description": "The appointment's outcome.",
                    "enum": [
                      "confirmed",
                      "completed",
                      "no_show",
                      "cancelled"
                    ]
                  },
                  "title": {
                    "type": "string",
                    "description": "Max 200."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Max 2000. null clears them."
                  },
                  "location": {
                    "type": "string",
                    "description": "Address or place, max 300. null clears it."
                  },
                  "host_user_id": {
                    "type": "string",
                    "description": "Team member who takes it. null for nobody."
                  },
                  "notify_lead": {
                    "type": "boolean",
                    "description": "false: the lead gets no more reminder texts or invite updates for this appointment. true: they do again."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "Link an appointment with no lead to this lead (same sub-account). Cannot move an appointment from one lead to another."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "status": "completed",
                "notes": "Signed the quote on site."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/members": {
      "get": {
        "operationId": "list_members",
        "tags": [
          "Members"
        ],
        "summary": "List sub-account members and invites",
        "description": "Each member has `user_id`, role, email and `full_name`. Use `user_id` (or the email) to name a team member in busy blocks. Staff and Technicians, who have no Team page in the app, get names and roles only (no emails, no invitations).\n\nRequired scope: `members:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "invite_member",
        "tags": [
          "Members"
        ],
        "summary": "Invite a member",
        "description": "Required scope: `members:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id."
                  },
                  "email": {
                    "type": "string",
                    "description": "Invitee email."
                  },
                  "role": {
                    "type": "string",
                    "description": "client_admin (Admin), client_viewer (Staff) or client_tech (Technician: only their own leads and appointments). Default client_viewer.",
                    "enum": [
                      "client_admin",
                      "client_viewer",
                      "client_tech"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "email"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/members/{member_id}": {
      "patch": {
        "operationId": "update_member_role",
        "tags": [
          "Members"
        ],
        "summary": "Change a member's role",
        "description": "You cannot change your own role.\n\nRequired scope: `members:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "member_id",
            "in": "path",
            "required": true,
            "description": "Member id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "description": "client_admin (Admin), client_viewer (Staff) or client_tech (Technician: only their own leads and appointments).",
                    "enum": [
                      "client_admin",
                      "client_viewer",
                      "client_tech"
                    ]
                  }
                },
                "required": [
                  "role"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "remove_member",
        "tags": [
          "Members"
        ],
        "summary": "Remove a member",
        "description": "Required scope: `members:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "member_id",
            "in": "path",
            "required": true,
            "description": "Member id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms": {
      "get": {
        "operationId": "list_smart_forms",
        "tags": [
          "Smart forms"
        ],
        "summary": "List smart forms",
        "description": "Required scope: `smart_forms:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_smart_form",
        "tags": [
          "Smart forms"
        ],
        "summary": "Create a smart form",
        "description": "Starts unpublished with the same defaults as a form created in the app.\n\n- The response includes its public path (/f/<slug>), `qualifier_questions`, `custom_fields`, qualification, `calendar_routing`, `service_area` and estimate.\n- Questions can ask for photos (`field_type` file) and put a price on answers (`option_prices`) for the instant estimate: switched on with estimate, the answers' prices add up to a live total in the form's footer, saved on the lead with its total as the deal value.\n- Qualification routes each lead to Qualified, Nurture or Not eligible: yes/no `qualifier_questions` (asked first when `qualifier_enabled` is on) and choice questions with `disqualify_options` or `nurture_options`.\n- A service area (`fields.address.service_area`) only accepts addresses in chosen US states or within a radius: address suggestions stay inside it and an out-of-area visitor sees your message and cannot send the form; switching it on shows and requires the address, like the builder.\n- Design and tracking pixels are edited in the app.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Form name (max 80)."
                  },
                  "headline": {
                    "type": "string",
                    "description": "Max 160."
                  },
                  "subheadline": {
                    "type": "string",
                    "description": "Max 300."
                  },
                  "primary_color": {
                    "type": "string",
                    "description": "#rrggbb."
                  },
                  "bullet_points": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 8 short lines."
                  },
                  "layout_mode": {
                    "type": "string",
                    "description": "The builder's Layout: single_step (one page, the default), multi_step (a step-by-step wizard), conversational (one question at a time, like a chat) or funnel (one big question per screen).",
                    "enum": [
                      "single_step",
                      "multi_step",
                      "conversational",
                      "funnel"
                    ]
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "Calendar used by the booking step."
                  },
                  "calendar_routing": {
                    "type": "boolean",
                    "description": "Pick the calendar from the answers: the sub-account's calendar routing rules (/v1/calendar-routes) choose which calendar's times the form shows once the deciding question is answered; calendar_id is used when no rule fits."
                  },
                  "booking_enabled": {
                    "type": "boolean",
                    "description": "Show the booking step."
                  },
                  "fields": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Contact fields: {\"email\":{\"required\":false},\"address\":{\"enabled\":false}}. Keys: first_name, last_name, phone, email, address, state (a State / Province pick list), notes. Phone or email must stay on. address also takes service_area (merged): {\"enabled\":true,\"mode\":\"states\",\"states\":[\"TX\",\"OK\"],\"message\":\"Sorry, we only serve Texas and Oklahoma.\"}, or mode \"radius\" with \"center\":{\"lat\":32.7767,\"lng\":-96.797,\"label\":\"Dallas, TX\"} and \"radius_miles\" (1-500, default 25). A blank message shows \"Sorry, we don't service this area yet.\"; null or enabled:false switches it off."
                  },
                  "is_published": {
                    "type": "boolean",
                    "description": "Default false."
                  },
                  "show_logo": {
                    "type": "boolean",
                    "description": "Off hides the logo above the headline and in the flow's header."
                  },
                  "headline_size": {
                    "type": "string",
                    "description": "The headline's own size; auto is what the layout picks.",
                    "enum": [
                      "auto",
                      "small",
                      "medium",
                      "large"
                    ]
                  },
                  "submit_note": {
                    "type": "string",
                    "description": "Small print right above the submit button (consent, a disclaimer), up to 400 characters; null removes it."
                  },
                  "steps_hint": {
                    "type": "boolean",
                    "description": "Booking forms: \"Complete the steps above to book.\" under the button. Off hides it."
                  },
                  "details_heading_on": {
                    "type": "boolean",
                    "description": "Single page and step by step: the heading above the contact details (\"1. Your information\"). Off hides it; on by default."
                  },
                  "details_heading": {
                    "type": "string",
                    "description": "That heading's words, up to 80 characters; null = \"Your information\" in the visitor's language."
                  },
                  "section_numbers": {
                    "type": "boolean",
                    "description": "Single page: \"1.\" \"2.\" in front of each section's heading. Off drops them; on by default."
                  },
                  "video": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "A video sales letter at the top (Builder > Content > Video at the top): { url: a YouTube (watch, youtu.be, Shorts), Vimeo, Loom or Wistia link, or an https link to a video file; position: below (default) or above the headline; autoplay (muted, with a Tap for sound button); poster (a cover picture for a file); ratio (width / height, default the video's own); enabled }. A new url turns it on; fields left out keep what the form has; null turns it off and keeps the link. The response carries video."
                  },
                  "qualifier_enabled": {
                    "type": "boolean",
                    "description": "Ask the qualifier_questions first."
                  },
                  "qualifier_questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 10, replaces the list: [{ text (max 200), disqualify_on: \"yes\" | \"no\" (default \"no\"), outcome: \"not_eligible\" | \"nurture\" (default \"not_eligible\") }]."
                  },
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Custom questions, up to 30, replaces the list: [{ key?, label (max 160), field_type: text | textarea | number | money | phone | email | url | select | multiselect | boolean | date | datetime | rating | file (photos or PDFs, up to 6, shown on the lead), options (select / multiselect: 2-40), option_prices? (select / multiselect: cents per answer for the instant estimate, e.g. {\"SUV\": 8000}; left out keeps the saved prices, null removes them), disqualify_options? or nurture_options? (choice types; boolean answers \"yes\" / \"no\"; never both), placement?: \"qualify\" | \"details\" (qualify = choice types only), option_style?: dropdown | buttons | cards | auto, no_first? (boolean: show No before Yes), after_contact? (details questions: asked after name, phone and email, e.g. a Comments box at the bottom; left out keeps the saved spot), allow_other? (select / multiselect: an Other answer with a box for their own words; left out keeps the saved choice), required?, enabled?, save_to_crm? (never for file), placeholder?, helper_text? }]."
                  },
                  "qualification": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Merged: { save_not_eligible: boolean, nurture_page: { headline, subheadline, cta_label, cta_url, redirect_url } }."
                  },
                  "estimate": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The instant price estimate, merged: { enabled, label (default \"Your estimate\"), base_cents (added before any answer), note (e.g. \"Final price after we see the job\"), range_percent (0-50: shown as a range that far either side) }. null switches it off."
                  },
                  "hidden_fields": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Values the visitor never sees, sent with each lead (the 20 at most; {key} and {cf_key} work in messages). Each { key, label, source, param, page, value }: source param reads ?<param>= (default the key) on the form link or the page it is embedded on (or the embed code's data-field-<key>); page reads the embedding page: page = year, make, model, price, vin, sku, condition, item, title, heading or url (the listing's schema.org data, the title, the main heading...), css:<selector> or meta:<name>; fixed is always value (value is also the fallback when a param or page finds nothing)."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Roof quote",
                "qualifier_enabled": true,
                "qualifier_questions": [
                  {
                    "text": "Do you own the home?",
                    "disqualify_on": "no",
                    "outcome": "not_eligible"
                  }
                ],
                "questions": [
                  {
                    "label": "When do you want to start?",
                    "field_type": "select",
                    "options": [
                      "This month",
                      "In 1-3 months",
                      "Just researching"
                    ],
                    "nurture_options": [
                      "Just researching"
                    ],
                    "placement": "qualify"
                  },
                  {
                    "label": "Vehicle size",
                    "field_type": "select",
                    "options": [
                      "Car",
                      "SUV",
                      "Truck"
                    ],
                    "option_prices": {
                      "Car": 31500,
                      "SUV": 38500,
                      "Truck": 45000
                    }
                  },
                  {
                    "label": "Photos of the damage",
                    "field_type": "file"
                  }
                ],
                "qualification": {
                  "save_not_eligible": true
                },
                "estimate": {
                  "enabled": true,
                  "note": "Final price after we see the job",
                  "range_percent": 10
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/submissions": {
      "get": {
        "operationId": "list_form_submissions",
        "tags": [
          "Smart forms"
        ],
        "summary": "List form submissions",
        "description": "Required scope: `smart_forms:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Default 50.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations": {
      "get": {
        "operationId": "list_ws_automations",
        "tags": [
          "CRM automations"
        ],
        "summary": "List sub-account automations",
        "description": "Required scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "Build an automation",
        "description": "Saved exactly as the Automations page saves it, so it opens and edits in the app.\n\n- Saved OFF unless enabled is true; once on, its texts and emails go to real leads through the normal quiet hours, opt-out and daily limits.\n- Steps can send lead data out (webhooks, alerts), so this needs an admin-scoped key.\n- Everything it points at (stages, team members, phone numbers, review pages, Facebook pages, Smart Forms, calendars, email senders) must be in the same sub-account; `GET /v1/workspace-automations/reference` lists them.\n- Any step can take a label (its name on the step card).\n- Steps include drip (let a number of leads through every period, the rest wait in line, within business hours if asked); triggers include `custom_field_changed` (a custom field changes, optionally to certain values or only by a person) and `yearly_date` (every year on a holiday or a date, at a time, for everyone matching `only_if` that day).\n- An `inbound_webhook` automation comes back with its private `inbound_url`: POST JSON with a phone or email to start it (it must be on), and every field sent can be used in its messages as `{field}`.\n\nRequired scope: `workspace_automations:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 80 characters."
                  },
                  "description": {
                    "type": "string",
                    "description": "Optional note."
                  },
                  "trigger": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "When it starts: {\"type\":\"new_lead\"}, {\"type\":\"stage_changed\",\"to_stages\":[\"booked\"]}, {\"type\":\"tag_added\",\"tags\":[\"hot\"]}, {\"type\":\"leads_imported\",\"tags\":[\"Foreclosure list\"]}, {\"type\":\"smart_form_submitted\",\"form_ids\":[\"Free quote\"]}, {\"type\":\"appointment_booked\",\"calendar_ids\":[\"Estimate visit\"]}, {\"type\":\"inbound_webhook\"}... Ids or names. See GET /v1/workspace-automations/reference."
                  },
                  "only_if": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Entry rules, all must hold: [{\"field\":\"tags\",\"op\":\"has_none\",\"value\":[\"customer\"]}]."
                  },
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "In order: [{\"action\":\"send_text\",\"message\":\"Hi {first_name}\"},{\"action\":\"wait\",\"days\":1},{\"action\":\"send_email\",\"subject\":\"Your quote\",\"message\":\"..\",\"from_sender_id\":\"<email sender id, address or name>\"},{\"action\":\"if\",\"conditions\":[..],\"then\":[..],\"else\":[..]}]. A send_text step takes send_as (auto, imessage or sms) when the sub-account has an iMessage Mac, plus voice_note_url (an https audio file sent right after the message, only from a connected iPhone number, never the business number; the step is skipped when no iPhone is connected) and video_url (texted as a link under the message). A send_email step takes format: simple (the default, message as rich text), designed (a branded email built from sections: design {headline, heroImageUrl, greeting, blocks [{type:text, md} | offer | image | features | steps | quote | gallery | banner | faq | cards | button | divider], ctaLabel, ctaUrl ({booking_link}, {review_link}, {reschedule_link} or https), signoff, signerName, accent, design {template classic|bold|letter|flyer|newsletter|elegant|minimal|bright|fresh|blocks|retro|night|soft}}; GET /v1/workspace-automations/email-design has the whole shape and an example) or html (html: the whole email in your own HTML; {first_name}, {{contact.first_name}} and *|FNAME|* are filled). Designed and html emails need a subject, get the business's logo, address and an Unsubscribe link, and their split_test b is {subject, preheader}."
                  },
                  "settings": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{\"stop_on_reply\":true,\"sending_window\":{\"days\":[\"mon\",\"tue\"],\"start\":\"09:00\",\"end\":\"18:00\"}}."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Default false."
                  }
                },
                "required": [
                  "workspace_id",
                  "name",
                  "trigger",
                  "steps"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Speed to lead",
                "trigger": {
                  "type": "new_lead"
                },
                "steps": [
                  {
                    "action": "send_text",
                    "message": "Hi {first_name}, thanks for reaching out! When is a good time to talk?"
                  },
                  {
                    "action": "wait",
                    "days": 1
                  },
                  {
                    "action": "send_text",
                    "message": "Still interested, {first_name}?"
                  }
                ],
                "settings": {
                  "stop_on_reply": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/{automation_id}/enroll": {
      "post": {
        "operationId": "enroll_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "Enroll leads into an automation",
        "description": "Can send real texts and emails. Confirm the lead list before calling.\n\n- Leads are queued and start within the sub-account's daily contact limit.\n- A lead already waiting in this automation's queue is not queued again (`already_queued`).\n- `ignore_filters` defaults to false: a lead that fails the automation's `only_if` rules is skipped when the queue reaches it (the app's Enroll dialog defaults to true).\n\nRequired scope: `workspace_automations:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lead_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Lead ids (max 5000)."
                  },
                  "ignore_filters": {
                    "type": "boolean",
                    "description": "Default false: leads that fail the automation's only_if rules are skipped. true = enroll them anyway."
                  }
                },
                "required": [
                  "lead_ids"
                ],
                "additionalProperties": true
              },
              "example": {
                "lead_ids": [
                  "uuid"
                ],
                "ignore_filters": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "queued": 1,
                    "skipped": 0,
                    "already_queued": 0,
                    "automation": {
                      "id": "uuid",
                      "name": "Speed to lead"
                    },
                    "batch_id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/{automation_id}/toggle": {
      "post": {
        "operationId": "toggle_ws_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "Enable or disable a sub-account automation",
        "description": "Required scope: `workspace_automations:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "Omit to flip the current state."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/reference": {
      "get": {
        "operationId": "automation_reference",
        "tags": [
          "CRM automations"
        ],
        "summary": "Every trigger, step, filter and setting the builder accepts",
        "description": "Read this before building: trigger types and their filters, step actions and their fields, entry-rule fields and operators (with every lead source), settings, message variables, and what this sub-account has for a definition to point at: stages, team, custom fields, phone numbers, review funnel, Facebook pages, Smart Forms, form names (for `form_name` rules), calendars and email senders.\n\nRequired scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/email-design": {
      "get": {
        "operationId": "automation_email_design",
        "tags": [
          "CRM automations"
        ],
        "summary": "How a designed automation email is built",
        "description": "The shape of a `send_email` step's design (format designed): its fields, every section (text, offer, image, features, steps, review, gallery, banner, questions, services, button, divider, custom HTML), the looks it can have, the rules (merge fields, [bracketed blanks], no invented facts) and a whole example step.\n\n- A designed email is drawn in the business's own logo, name and address with a footer and Unsubscribe link, exactly as the Automations page's email designer shows it.\n- The same for every sub-account.\n\nRequired scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/{automation_id}": {
      "get": {
        "operationId": "get_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "One automation as {trigger, only_if, steps, settings}",
        "description": "The same shape create and update take (step names included), with a ref on every step so an update can keep steps unchanged (`{\"keep\":\"<ref>\"}`).\n\n- Webhook header values are hidden.\n- An `inbound_webhook` automation includes its `inbound_url`; viewers see only its host, like webhook step links.\n\nRequired scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "Change an automation",
        "description": "Send only what changes. steps replaces all steps: keep unchanged ones with `{\"keep\":\"<ref>\"}` from GET. settings changes only the keys sent. enabled turns it on or off.\n\nRequired scope: `workspace_automations:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "New name."
                  },
                  "trigger": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "New trigger."
                  },
                  "only_if": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "New entry rules."
                  },
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "New steps (replaces all)."
                  },
                  "settings": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Settings to change."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "On or off."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "Delete an automation",
        "description": "Leads inside it stop where they are.\n\nRequired scope: `workspace_automations:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/{automation_id}/results": {
      "get": {
        "operationId": "automation_results",
        "tags": [
          "CRM automations"
        ],
        "summary": "How an automation's texts and emails did",
        "description": "Every Send text and Send email step with its sends, opens, clicks, hard bounces and replies within 7 days of each send, the numbers in the app's Stats view.\n\n- Rates are fractions (0.25 = 25%).\n- A text has no opens, clicks or bounces: those are null.\n- A step with a split test also has `split_test`: each version's numbers and a verdict.\n- status is `too_early` (fewer than 30 sends on a version; `sends_needed` says how many more), tie, leading (ahead, could still be chance) or winner (95% confidence); metric is what it is judged on (clicks for an email with at least 5 clicks, else opens; replies for a text); lift is how far ahead as a fraction, null when the other version's rate is 0.\n- Steps are matched by their place in the automation; sends from a place that no longer holds that kind of step are in `steps_no_longer_there`.\n- partial is true when the period has more runs than the 2,000 newest counted.\n\nRequired scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "The period: 7, 30 or 90. Default 30.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "automation": {
                      "id": "uuid",
                      "name": "Speed to lead",
                      "enabled": true
                    },
                    "days": 30,
                    "since": "2026-10-11T14:00:00Z",
                    "runs": 240,
                    "replies_within_days": 7,
                    "steps": [
                      {
                        "ref": "1",
                        "action": "send_text",
                        "about": "Hi {first_name}, thanks for reaching out",
                        "sends": 240,
                        "opens": null,
                        "clicks": null,
                        "hard_bounces": null,
                        "replies": 61,
                        "open_rate": null,
                        "click_rate": null,
                        "reply_rate": 0.2542
                      },
                      {
                        "ref": "3",
                        "action": "send_email",
                        "about": "Your free quote",
                        "sends": 200,
                        "opens": 118,
                        "clicks": 31,
                        "hard_bounces": 2,
                        "replies": 9,
                        "open_rate": 0.59,
                        "click_rate": 0.155,
                        "reply_rate": 0.045,
                        "split_test": {
                          "running": true,
                          "percent_b": 50,
                          "versions": {
                            "A": {
                              "sends": 100,
                              "opens": 52,
                              "clicks": 9,
                              "hard_bounces": 1,
                              "replies": 4,
                              "open_rate": 0.52,
                              "click_rate": 0.09,
                              "reply_rate": 0.04
                            },
                            "B": {
                              "sends": 100,
                              "opens": 66,
                              "clicks": 22,
                              "hard_bounces": 1,
                              "replies": 5,
                              "open_rate": 0.66,
                              "click_rate": 0.22,
                              "reply_rate": 0.05
                            }
                          },
                          "verdict": {
                            "status": "winner",
                            "metric": "clicked",
                            "metric_label": "click rate",
                            "leader": "B",
                            "lift": 1.4444,
                            "says": "Version B wins on click rate (144% better)."
                          }
                        }
                      }
                    ],
                    "page": "/clients/uuid/automations"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/{automation_id}/duplicate": {
      "post": {
        "operationId": "duplicate_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "Copy an automation",
        "description": "The copy is saved OFF unless enabled is true.\n\nRequired scope: `workspace_automations:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The copy's name."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Default false."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/folders": {
      "get": {
        "operationId": "list_automation_folders",
        "tags": [
          "CRM automations"
        ],
        "summary": "List automation folders",
        "description": "The folders on the Automations page in their order, the automations in each, and the ones at the top level. `GET /v1/workspace-automations` also takes `folder_id` (or none for the top level).\n\nRequired scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "folders": [
                      {
                        "id": "uuid",
                        "name": "Reminders",
                        "position": 1,
                        "created_at": "2026-10-26T10:00:00Z",
                        "automations": [
                          {
                            "id": "uuid",
                            "name": "24 h reminder",
                            "enabled": true
                          }
                        ]
                      }
                    ],
                    "top_level": [
                      {
                        "id": "uuid",
                        "name": "New lead welcome",
                        "enabled": true
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_automation_folder",
        "tags": [
          "CRM automations"
        ],
        "summary": "Create an automation folder",
        "description": "Added after the existing folders.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspace_automations:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 60 characters."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Reminders"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "folder": {
                      "id": "uuid",
                      "name": "Reminders",
                      "position": 2,
                      "created_at": "2026-10-29T10:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/folders/{folder_id}": {
      "patch": {
        "operationId": "rename_automation_folder",
        "tags": [
          "CRM automations"
        ],
        "summary": "Rename an automation folder",
        "description": "Required scope: `workspace_automations:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folder_id",
            "in": "path",
            "required": true,
            "description": "The folder.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 60 characters."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "name": "Appointment reminders"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "folder": {
                      "id": "uuid",
                      "name": "Appointment reminders"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_automation_folder",
        "tags": [
          "CRM automations"
        ],
        "summary": "Delete an automation folder",
        "description": "Its automations move to the top level, unchanged (nothing is turned off or deleted).\n\nRequired scope: `workspace_automations:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folder_id",
            "in": "path",
            "required": true,
            "description": "The folder.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "uuid",
                    "deleted": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/move": {
      "post": {
        "operationId": "move_automations",
        "tags": [
          "CRM automations"
        ],
        "summary": "Move automations into a folder",
        "description": "Puts the automations into the folder, or back to the top level with `folder_id` null. Only where they show on the page changes.\n\nRequired scope: `workspace_automations:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "automation_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 100 automations of the sub-account."
                  },
                  "folder_id": {
                    "type": "string",
                    "description": "The folder, or null for the top level."
                  }
                },
                "required": [
                  "workspace_id",
                  "automation_ids",
                  "folder_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "automation_ids": [
                  "uuid"
                ],
                "folder_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "moved": 1,
                    "folder_id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/{automation_id}/enrollments": {
      "get": {
        "operationId": "list_automation_enrollments",
        "tags": [
          "CRM automations"
        ],
        "summary": "Who is inside an automation right now",
        "description": "Leads waiting on a step or mid-step, newest first, with the time their next step runs, plus how many are still waiting to be enrolled.\n\nRequired scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 100.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "automation": {
                      "id": "uuid",
                      "name": "Speed to lead",
                      "steps_total": 3
                    },
                    "enrollments": [
                      {
                        "run_id": "uuid",
                        "lead": {
                          "id": "uuid",
                          "full_name": "Jane Doe",
                          "phone": "+14155550123"
                        },
                        "status": "waiting",
                        "step_index": 1,
                        "started_at": "2026-09-30T14:00:00Z",
                        "next_step_at": "2026-10-01T14:00:00Z"
                      }
                    ],
                    "waiting_to_enroll": 0,
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspace-automations/{automation_id}/unenroll": {
      "post": {
        "operationId": "unenroll_automation",
        "tags": [
          "CRM automations"
        ],
        "summary": "Take leads out of an automation",
        "description": "Like Remove from workflow in the app: their run stops, queued steps (texts, emails) are cancelled and the lead's timeline notes it. Nothing is sent.\n\nRequired scope: `workspace_automations:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "automation_id",
            "in": "path",
            "required": true,
            "description": "Automation id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lead_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 500 lead ids."
                  },
                  "all": {
                    "type": "boolean",
                    "description": "true = everyone in it (instead of lead_ids)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "lead_ids": [
                  "uuid"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "automation_id": "uuid",
                    "removed": 1,
                    "waiting_cancelled": 0
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/workflows": {
      "get": {
        "operationId": "list_lead_workflows",
        "tags": [
          "CRM automations"
        ],
        "summary": "The automations a lead is inside",
        "description": "Required scope: `workspace_automations:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead_id": "uuid",
                    "workflows": [
                      {
                        "run_id": "uuid",
                        "automation_id": "uuid",
                        "name": "Speed to lead",
                        "status": "waiting",
                        "step_index": 1,
                        "started_at": "2026-09-30T14:00:00Z",
                        "next_step_at": "2026-10-01T14:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspaces": {
      "get": {
        "operationId": "list_workspaces",
        "tags": [
          "Workspaces"
        ],
        "summary": "List sub-accounts",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspaces/{workspace_id}": {
      "get": {
        "operationId": "get_workspace",
        "tags": [
          "Workspaces"
        ],
        "summary": "Get one sub-account",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_workspace",
        "tags": [
          "Workspaces"
        ],
        "summary": "Update a sub-account",
        "description": "Changes a sub-account's settings. Send only what changes.\n\nWho can change what:\n- Owners and admins of the sub-account: `name`, `timezone`, `industry`, `logo_url`, `notify_on_appointments`, `enabled_features`.\n- Only the agency (the owner or an agency admin): `archived`, `brand_id`, `hidden_features`, `monthly_credit_limit`. Anyone else gets 403.\n\nenabled_features is Settings > Features: tools only some businesses use, off until turned on. Send { key: true | false }; only the keys sent change.:\n- `sales`: the Sales page, and parts, tip and technician on won jobs.\n- `plans`: Plans & memberships on won jobs.\n- `pipelines`: More pipelines.\n- `quote_templates`: Quote templates on estimates.\n- `new_numbers_in_messages`: texts and calls from numbers the CRM doesn't know stay conversations in Messages (`chat_only` true on the lead) until they book or someone adds them to Leads.\n\nhidden_features is what the agency hides from the sub-account's own people. Client admins, Staff and Technicians lose those pages, and their API keys get 403 feature_off on those routes. Send { key: true | false }; only the keys sent change.:\n- Pages: `leads`, `messages`, `appointments`, `calendars`, `smart_forms`, `media`, `campaigns`, `calls`, `ai_voice`, `automations`, `landing_pages`, `invoices`, `sales`, `reports`, `refer`, `activity`, `team`, `ad_insights`, `support`, `agent`, `contracts`, `proposals`.\n- `tools` hides the whole Tools page. One key per tool: `email_marketing`, `reward_games`, `loyalty_cards`, `short_links`, `website_analytics`, `click_guard`, `call_tracking`, `seo_tracker`, `offer_generator`, `website_widget`, `review_funnel`, `ai_visibility`, `listings`.\n- `google` hides every Google tool. One key each: `google_reviews`, `google_posts`, `google_optimizer`, `google_rankings`, `google_desk`, `google_reports`, `google_embeds`.\n- A sub-account on an agency plan also follows what the plan leaves out (Agency > Plans & add-ons). A key sent here is this sub-account's own choice.\n\n`monthly_credit_limit` is the most credits the sub-account may use in your billing period, every tool together. At the limit its texts, emails, AI and paid tools pause until the period renews; incoming texts and calls still come in. null means no limit.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The sub-account's name, up to 120 characters."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "An IANA time zone, e.g. America/Chicago."
                  },
                  "industry": {
                    "type": "string",
                    "description": "Up to 80 characters."
                  },
                  "notify_on_appointments": {
                    "type": "boolean",
                    "description": "Alert the team when an appointment is booked."
                  },
                  "archived": {
                    "type": "boolean",
                    "description": "Agency only. Archives the sub-account, or brings it back."
                  },
                  "brand_id": {
                    "type": "string",
                    "description": "Agency only. One of your brands (GET /v1/brands), or null."
                  },
                  "monthly_credit_limit": {
                    "type": "number",
                    "description": "Agency only. A whole number of credits, 0 to 10,000,000, or null for no limit."
                  },
                  "logo_url": {
                    "type": "string",
                    "description": "Client logo URL, or null to remove it."
                  },
                  "enabled_features": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Settings > Features, e.g. { \"sales\": true }."
                  },
                  "hidden_features": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Hidden from the client's people, e.g. { \"invoices\": true, \"team\": false }. Owner or agency admin."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Delgado Garage Doors",
                "timezone": "America/Chicago",
                "enabled_features": {
                  "sales": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspaces/{workspace_id}/outreach": {
      "post": {
        "operationId": "configure_outreach",
        "tags": [
          "Workspaces"
        ],
        "summary": "Configure outreach (auto-greet, AI replies, sending identity)",
        "description": "Sets a sub-account's outreach settings by their raw column names. PATCH on the same path does the same.\n\nPrefer `PATCH /v1/ai-texting` and `/v1/nurture-sequence`: they take friendly names and check every value. Here, unknown fields are ignored and text is capped at 20,000 characters.\n\nFirst text and email:\n- `auto_greet_new_leads`, `first_message_template`, `sms_template`, `sms_enabled`.\n- `greet_delay_minutes_smart_form`, `greet_delay_minutes_default`.\n- `email_enabled`, `email_from_address`, `email_from_name`, `email_subject`, `email_template`.\n\nAI replies:\n- `ai_enabled`, `ai_system_prompt`, `ai_business_context`, `ai_agent_name`, `ai_booking_link`.\n- `ai_max_auto_replies`, `reply_delay_minutes`, `ai_auto_resume_minutes`.\n- `handoff_on_unknown`, `handoff_pause_ai`, `handoff_resume_days`.\n- `ai_can_cancel_appointments`, `ai_cancel_retention_enabled`, `ai_cancel_retention_note`.\n\nWhen things may send:\n- `greet_window_mode`, `greet_window_start`, `greet_window_end`.\n- `followup_window_mode`, `followup_window_start`, `followup_window_end`.\n- `respect_business_hours`, `quiet_hours_enabled`, `quiet_hours_start`, `quiet_hours_end`.\n\nFollow-ups, missed calls and reminders:\n- `nurture_enabled`, `nurture_steps`.\n- `missed_call_text_enabled`, `missed_call_text_body`.\n- `reminder_24h_enabled`, `reminder_24h_template`, `reminder_1h_enabled`, `reminder_1h_template`.\n- `reminder_5m_enabled`, `reminder_5m_template` (the 5-minute reminder, off by default).\n- `customer_confirmation_enabled`, `customer_confirmation_template`.\n- `appointment_email_enabled`, `appointment_email_language` (en | es).\n\nAnyone who can manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "Sub-account id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "auto_greet_new_leads": {
                    "type": "boolean",
                    "description": "Text new leads automatically."
                  },
                  "first_message_template": {
                    "type": "string",
                    "description": "The first text."
                  },
                  "ai_enabled": {
                    "type": "boolean",
                    "description": "AI replies on or off."
                  },
                  "ai_agent_name": {
                    "type": "string",
                    "description": "Name the AI texts as."
                  },
                  "email_from_name": {
                    "type": "string",
                    "description": "Sender name on emails."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "auto_greet_new_leads": true,
                "ai_enabled": true,
                "ai_agent_name": "Sarah"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/setup-status": {
      "get": {
        "operationId": "setup_status",
        "tags": [
          "Setup"
        ],
        "summary": "What is set up, and what is missing",
        "description": "Start here. Returns the sub-account's real configuration (numbers, AI texting, receptionist, calendars, forms, automations, offers, team, lead sources, integrations) and a severity-ranked list of findings.\n\nEach finding names the API call and MCP tool that fixes it, or says when it can only be done in the app (buying a number, SMS registration, connecting Google or Outlook).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/offers": {
      "get": {
        "operationId": "list_offers",
        "tags": [
          "Offers"
        ],
        "summary": "List offers",
        "description": "Offers (offer playbooks) tell the AI what this business sells to a lead: the first text, the follow-up sequence, notes for the AI and the booking link.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_offer",
        "tags": [
          "Offers"
        ],
        "summary": "Create an offer",
        "description": "Required scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Internal name (max 80)."
                  },
                  "offer_label": {
                    "type": "string",
                    "description": "How the offer is described to the lead (max 200)."
                  },
                  "first_message_template": {
                    "type": "string",
                    "description": "First text to a new lead. Supports {{first_name}} (max 1600)."
                  },
                  "nurture_enabled": {
                    "type": "boolean",
                    "description": "null follows the sub-account's own follow-up setting."
                  },
                  "nurture_steps": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 12 follow-ups: { offset_minutes, body_template }. offset_minutes counts from the previous message."
                  },
                  "ai_context_note": {
                    "type": "string",
                    "description": "What the AI should know about this offer (max 2000)."
                  },
                  "booking_link": {
                    "type": "string",
                    "description": "Public http(s) URL."
                  },
                  "is_active": {
                    "type": "boolean",
                    "description": "Default true."
                  },
                  "smart_first_text_enabled": {
                    "type": "boolean",
                    "description": "true: the AI writes the first text for these leads (first_message_template is the backup); false: first_message_template goes out as written; null (default) follows the sub-account's smart first text switch."
                  },
                  "smart_first_text_instructions": {
                    "type": "string",
                    "description": "What the smart first text should do for these leads (max 1000). Empty uses the sub-account's instructions."
                  },
                  "triggers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Which leads get this offer: { type, value, label? }. type is meta_form, smart_form, webhook (a lead source id) or source (the lead's source text). Form and lead-source ids must belong to the sub-account."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Free roof inspection",
                "offer_label": "a free 20-point roof inspection",
                "first_message_template": "Hi {{first_name}}, thanks for asking about a free roof inspection. What day works best?",
                "nurture_steps": [
                  {
                    "offset_minutes": 60,
                    "body_template": "Still want that inspection?"
                  }
                ],
                "triggers": [
                  {
                    "type": "source",
                    "value": "Website form"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/offers/{offer_id}": {
      "patch": {
        "operationId": "update_offer",
        "tags": [
          "Offers"
        ],
        "summary": "Update an offer",
        "description": "Send only what changes. `triggers`, when sent, replaces the whole list.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offer_id",
            "in": "path",
            "required": true,
            "description": "Offer id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_offer",
        "tags": [
          "Offers"
        ],
        "summary": "Delete an offer",
        "description": "Required scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offer_id",
            "in": "path",
            "required": true,
            "description": "Offer id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendars/{calendar_id}": {
      "patch": {
        "operationId": "update_calendar",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Update a booking calendar",
        "description": "Takes the same fields as create; send only what changes. `hosts`, when sent, replaces the pool; people who stay keep their place in the rotation.\n\n- An `arrival_window` calendar always keeps `buffer_minutes` at 0 (a full-day one keeps its buffer).\n- `appointment_texts` changes only the texts it names.\n- pricing, design and fields merge; `pricing.options`, `pricing.addons` and questions replace their lists.\n- Turning pricing off also stops taking payment at booking.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "calendar_id",
            "in": "path",
            "required": true,
            "description": "Calendar id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              },
              "example": {
                "pricing": {
                  "deposit": {
                    "mode": "percent",
                    "percent": 20
                  }
                },
                "design": {
                  "colors": {
                    "button": "#d4a63a"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendars/{calendar_id}/copy-design": {
      "post": {
        "operationId": "copy_calendar_design",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Copy a calendar's design to others",
        "description": "The Design tab's \"Use on other calendars\": this calendar's design goes onto the calendars named (or every other calendar of the sub-account with all: true), switched on.\n\n- A calendar that has its own cover photo keeps it.\n- The calendar must have a design switched on.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "calendar_id",
            "in": "path",
            "required": true,
            "description": "The calendar whose design is copied.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "calendar_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The calendars to copy it to."
                  },
                  "all": {
                    "type": "boolean",
                    "description": "Every other calendar of the sub-account instead."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "all": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "from_calendar_id": "uuid",
                    "copied_to": [
                      {
                        "id": "uuid",
                        "name": "Quick wash"
                      }
                    ],
                    "design": {
                      "enabled": true,
                      "preset": "showroom",
                      "mode": "dark"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendars/{calendar_id}/design/generate": {
      "post": {
        "operationId": "generate_calendar_design",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Design a booking page with AI",
        "description": "The Design tab's AI designer: describe the look in one line and/or give the business's website (its colours, fonts and logo are read from it).\n\n- Returns the design and a one-line summary, and saves it on the calendar unless save is false.\n- readable says whether the text reads well on the card.\n- No credits used.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "calendar_id",
            "in": "path",
            "required": true,
            "description": "Calendar id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instruction": {
                    "type": "string",
                    "description": "What it should look like, e.g. \"black and gold, like a luxury showroom\" (max 1200)."
                  },
                  "website_url": {
                    "type": "string",
                    "description": "The business's website."
                  },
                  "save": {
                    "type": "boolean",
                    "description": "Default true. false only returns the design (send it later with PATCH design)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "instruction": "black and gold, like a luxury showroom",
                "website_url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "design": {
                      "enabled": true,
                      "preset": null,
                      "mode": "dark",
                      "colors": {
                        "background": "#09090b",
                        "surface": "#141416",
                        "text": "#f5f5f4",
                        "button": "#d4a63a"
                      },
                      "font": "montserrat",
                      "heading_font": "oswald",
                      "radius": "soft",
                      "button_style": "solid",
                      "backdrop": "glow",
                      "layout": "card",
                      "header_align": "left",
                      "logo_size": "medium",
                      "day_style": "tiles",
                      "time_style": "grid",
                      "picked_style": "filled",
                      "shadow": "lifted",
                      "heading_case": "upper",
                      "logo_url": null,
                      "cover_url": null,
                      "background_url": null,
                      "hide_avatar": false,
                      "show_counts": true,
                      "group_times": true,
                      "labels": {
                        "pick_day": "",
                        "pick_time": "",
                        "done_title": "",
                        "done_text": ""
                      },
                      "custom_css": null
                    },
                    "summary": "Dark showroom look with gold buttons and condensed headings.",
                    "saved": true,
                    "website": {
                      "url": "https://example.com",
                      "read": true
                    },
                    "readable": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking-menus": {
      "get": {
        "operationId": "list_booking_menus",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "List service menus",
        "description": "Service menus (Calendars → Booking tools → Service menu): one booking link (/c/<slug>, `public_path`) that lists several calendars in sections, with search, category chips and sorting; the customer picks a service and books it there.\n\n- Each section lists its services with their price and length as the page shows them.\n- warnings says when its services are on separate schedules (two customers could book the same time on different services) or switched off.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "booking_menus": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "slug": "to-the-t-services",
                        "name": "All services",
                        "title": "Book a detail",
                        "description": null,
                        "sections": [
                          {
                            "id": "sec1",
                            "title": "Quick Services",
                            "description": null,
                            "calendar_ids": [
                              "uuid"
                            ],
                            "services": [
                              {
                                "calendar_id": "uuid",
                                "name": "Express wash",
                                "title": "Express wash",
                                "is_active": true,
                                "price_from_cents": 6000,
                                "price_to_cents": 9000,
                                "length_label": "1-2 hr",
                                "schedule_group": "Main crew"
                              }
                            ]
                          }
                        ],
                        "options": {
                          "show_prices": true,
                          "show_durations": true,
                          "search": true,
                          "filters": true,
                          "sorting": true,
                          "default_sort": "featured"
                        },
                        "design": null,
                        "is_active": true,
                        "public_path": "/c/to-the-t-services",
                        "warnings": [],
                        "created_at": "2026-10-23T12:00:00Z",
                        "updated_at": "2026-10-23T12:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_booking_menu",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Create a service menu",
        "description": "Without sections it starts like the app's: one \"Services\" section with every calendar that is switched on, and a link named after the business. The link shares /c/ with calendars, so a slug a calendar or another menu uses answers 409.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "title": {
                    "type": "string",
                    "description": "Heading customers see (max 120). Default \"Book a service\"."
                  },
                  "name": {
                    "type": "string",
                    "description": "Internal name (max 80). Default \"All services\"."
                  },
                  "description": {
                    "type": "string",
                    "description": "Under the heading (max 600)."
                  },
                  "slug": {
                    "type": "string",
                    "description": "Link name: /c/<slug> (letters, numbers, dashes; max 40)."
                  },
                  "sections": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "In order, replacing the list: [{ id?, title (max 80), description?, calendar_ids: [calendar ids, in the order shown] }]. Up to 30 sections; every calendar must belong to the sub-account."
                  },
                  "options": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Merged: { show_prices, show_durations, search, filters (category chips), sorting, default_sort: featured | price_low | price_high | shortest | name }. All on by default."
                  },
                  "design": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The page look, the same shape as a calendar's design. It carries into each service's booking flow opened from the menu."
                  },
                  "is_active": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "title": "Book a detail",
                "sections": [
                  {
                    "title": "Quick Services",
                    "calendar_ids": [
                      "uuid",
                      "uuid"
                    ]
                  },
                  {
                    "title": "Detailing Packages",
                    "calendar_ids": [
                      "uuid"
                    ]
                  }
                ],
                "design": {
                  "preset": "showroom"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking-menus/{menu_id}": {
      "patch": {
        "operationId": "update_booking_menu",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Update a service menu",
        "description": "Takes the same fields as create; send only what changes. sections replaces the list; options and design merge.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "menu_id",
            "in": "path",
            "required": true,
            "description": "Menu id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": true
              },
              "example": {
                "options": {
                  "default_sort": "price_low"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_booking_menu",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Delete a service menu",
        "description": "Its link stops working; the calendars on it are not touched.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "menu_id",
            "in": "path",
            "required": true,
            "description": "Menu id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking-menus/{menu_id}/share-schedule": {
      "post": {
        "operationId": "share_menu_schedule",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Put a menu's services on one schedule",
        "description": "The menu editor's \"Share one schedule\": every calendar on the menu gets the same `schedule_group`, so a booking on any of them takes that time on all of them (one crew doing every service). group names it; by default the group one of them already has, else the menu's title.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "menu_id",
            "in": "path",
            "required": true,
            "description": "Menu id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "group": {
                    "type": "string",
                    "description": "The shared schedule's name (max 60)."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "schedule_group": "Main crew",
                    "calendar_ids": [
                      "uuid",
                      "uuid"
                    ],
                    "changed": [
                      "uuid"
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/booking-menus/{menu_id}/design/generate": {
      "post": {
        "operationId": "generate_menu_design",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Design a service menu with AI",
        "description": "Same as `POST /v1/calendars/{calendar_id}/design/generate`, for a service menu's page.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "menu_id",
            "in": "path",
            "required": true,
            "description": "Menu id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instruction": {
                    "type": "string",
                    "description": "What it should look like."
                  },
                  "website_url": {
                    "type": "string",
                    "description": "The business's website."
                  },
                  "save": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/availability": {
      "get": {
        "operationId": "get_availability",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Get business hours and booking defaults",
        "description": "Required scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_availability",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Set business hours and booking defaults",
        "description": "The AI uses these to decide when it may text and which times to offer. Setting the time zone also updates the sub-account's time zone.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA zone."
                  },
                  "weekly_hours": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Same shape as a calendar's."
                  },
                  "date_overrides": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Days off or special hours."
                  },
                  "slot_minutes": {
                    "type": "number",
                    "description": "5-240."
                  },
                  "buffer_minutes": {
                    "type": "number",
                    "description": "0-120. Always saved as 0 when scheduling_mode is arrival_window."
                  },
                  "default_calendar_id": {
                    "type": "string",
                    "description": "A calendar of this sub-account, or null."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "timezone": "America/Chicago",
                "weekly_hours": {
                  "mon": [
                    [
                      "08:00",
                      "17:00"
                    ]
                  ],
                  "sat": [
                    [
                      "09:00",
                      "13:00"
                    ]
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendar-routes": {
      "get": {
        "operationId": "list_calendar_routes",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "List calendar routing rules",
        "description": "Calendar routing (Calendars -> Calendar routing in the app) sends each lead to the calendar that fits their answers: \"Player group is Girls 13-14 -> Girls 13-14 calendar\".\n\n- Rules are checked in order (`position` 1 first); the first rule whose conditions ALL match the lead's custom fields or tags picks the calendar.\n- Smart Forms with `calendar_routing` on, the AI texter and the AI caller follow them.\n- Each rule comes with its calendar's name and a readable `summary`.\n- Rules that are switched off, or whose calendar is off, are skipped.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "calendar_routes": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "calendar_id": "uuid",
                        "calendar_name": "Girls 13-14",
                        "calendar_active": true,
                        "name": "Girls 13-14",
                        "conditions": [
                          {
                            "kind": "field",
                            "key": "player_group",
                            "op": "is",
                            "values": [
                              "Girls 13-14"
                            ],
                            "min": null,
                            "max": null
                          }
                        ],
                        "summary": "Player group is Girls 13-14",
                        "position": 1,
                        "is_active": true,
                        "created_at": "2026-10-07T18:00:00Z",
                        "updated_at": "2026-10-07T18:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_calendar_route",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Add a calendar routing rule",
        "description": "Added last unless you send `position`.\n\n- Conditions: a field condition reads a custom field by key (`GET /v1/custom-fields`) with op is, `is_not` or contains and `values` (any one matches), or op between with min and/or max for numbers (\"11 years old\" counts as 11); a tag condition (kind tag, op is or `is_not`) reads the lead's tags.\n- Answers compare ignoring case, accents and punctuation.\n- The calendar must belong to the sub-account.\n- `warnings` explains a rule that may never fire (a key that is not a custom field, a calendar that is switched off).\n\nWho can call it: Owners and admins only; at most 200 rules.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "The calendar this rule books on (GET /v1/calendars)."
                  },
                  "conditions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "All must match, 1-20: [{\"kind\":\"field\",\"key\":\"player_group\",\"op\":\"is\",\"values\":[\"Girls 13-14\"]}], [{\"kind\":\"field\",\"key\":\"age\",\"op\":\"between\",\"min\":9,\"max\":12}], [{\"kind\":\"tag\",\"op\":\"is\",\"values\":[\"VIP\"]}]."
                  },
                  "name": {
                    "type": "string",
                    "description": "Optional label, max 120."
                  },
                  "is_active": {
                    "type": "boolean",
                    "description": "Default true."
                  },
                  "position": {
                    "type": "number",
                    "description": "1 = checked first. Default last."
                  }
                },
                "required": [
                  "workspace_id",
                  "calendar_id",
                  "conditions"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "calendar_id": "uuid",
                "name": "Girls 13-14",
                "conditions": [
                  {
                    "kind": "field",
                    "key": "player_group",
                    "op": "is",
                    "values": [
                      "Girls 13-14"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "calendar_route": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "calendar_id": "uuid",
                      "calendar_name": "Girls 13-14",
                      "calendar_active": true,
                      "name": "Girls 13-14",
                      "conditions": [
                        {
                          "kind": "field",
                          "key": "player_group",
                          "op": "is",
                          "values": [
                            "Girls 13-14"
                          ],
                          "min": null,
                          "max": null
                        }
                      ],
                      "summary": "Player group is Girls 13-14",
                      "position": 3,
                      "is_active": true,
                      "created_at": "2026-10-16T18:00:00Z",
                      "updated_at": "2026-10-16T18:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendar-routes/{route_id}": {
      "patch": {
        "operationId": "update_calendar_route",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Change a calendar routing rule",
        "description": "Send any of `calendar_id`, name, conditions (replaces the list) and `is_active`. To move a rule use `POST /v1/calendar-routes/reorder`.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "route_id",
            "in": "path",
            "required": true,
            "description": "Rule id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "calendar_id": {
                    "type": "string",
                    "description": "Another calendar of the sub-account."
                  },
                  "conditions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the conditions (see create)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Max 120."
                  },
                  "is_active": {
                    "type": "boolean",
                    "description": "false keeps the rule but skips it."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "is_active": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_calendar_route",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Delete a calendar routing rule",
        "description": "Owners and admins only. The other rules keep their order.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "route_id",
            "in": "path",
            "required": true,
            "description": "Rule id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendar-routes/reorder": {
      "post": {
        "operationId": "reorder_calendar_routes",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Set the order rules are checked in",
        "description": "The first rule that matches wins, so put narrower rules first. `order` lists every rule id of the sub-account exactly once, first to last. Answers the rules in their new order.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "order": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Every rule id, first to last."
                  }
                },
                "required": [
                  "workspace_id",
                  "order"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "order": [
                  "uuid-rule-b",
                  "uuid-rule-a"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calendar-routes/match": {
      "get": {
        "operationId": "match_calendar_route",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Which calendar a lead routes to",
        "description": "Runs the rules the way the booking paths do (active rules on calendars that are on) against a lead's custom fields and tags, and/or `answers` you pass.\n\nstatus:\n- matched (`calendar` and the `route` that won)\n- pending (no rule matched yet but one still can: `missing_fields` are the answers to ask for before offering times)\n- unmatched (no rule fits: the form's or the AI's own calendar applies)\n- or `no_rules`\n\nViewers limited to their own leads only reach those leads.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": false,
            "description": "Sub-account id (omit on pinned keys). Needed without lead_id; with lead_id, the lead must be in it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "The lead to route. Send lead_id, answers or both.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "answers",
            "in": "query",
            "required": false,
            "description": "JSON object of field key to answer to try, laid over the lead's own, e.g. {\"player_group\":\"Girls 13-14\"}.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead_id": "uuid",
                    "status": "pending",
                    "calendar": null,
                    "route": null,
                    "missing_fields": [
                      {
                        "key": "player_group",
                        "label": "Player group"
                      }
                    ],
                    "rules_checked": 4
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/busy-blocks/{external_id}": {
      "put": {
        "operationId": "put_busy_block",
        "tags": [
          "Team busy times"
        ],
        "summary": "Add or update a team member's busy block",
        "description": "For a schedule kept in other software (a field-service app, a dispatch board): the person is treated as booked for that time, so the AI (text, chat and phone), Smart Forms, booking pages and round robin only offer times when they are free.\n\n- `external_id` is YOUR id for the block (a job or visit id, URL-encoded in the path); sending the same id again replaces the block, so it is safe to resend.\n- A block can make several people busy (a two-tech job).\n- Team members are named by user id or email (`GET /v1/members`); technicians must be invited as members first.\n- Times need a time zone (Z or an offset).\n- At most 31 days per block.\n- 201 when created, 200 when replaced (changed: false when nothing differed).\n\nWho can call it: Owners and admins of the sub-account only.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "description": "Your own id for the block: 1-200 letters, digits or . _ : ~ @ # | + = -",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "team_member": {
                    "type": "string",
                    "description": "The busy person: a team member's user id or email. Or team_members for several."
                  },
                  "team_members": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Several busy people (user ids or emails), up to 50."
                  },
                  "starts_at": {
                    "type": "string",
                    "description": "ISO 8601 with a zone, e.g. 2026-10-14T08:00:00-05:00."
                  },
                  "ends_at": {
                    "type": "string",
                    "description": "ISO 8601 with a zone; after starts_at."
                  },
                  "title": {
                    "type": "string",
                    "description": "Optional note shown to the team in the CRM calendar (never to leads or the AI), max 200."
                  }
                },
                "required": [
                  "workspace_id",
                  "starts_at",
                  "ends_at"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "team_member": "tech.alex@example.com",
                "starts_at": "2026-10-14T08:00:00-05:00",
                "ends_at": "2026-10-14T11:30:00-05:00",
                "title": "Job #4821 water heater install"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "busy_block": {
                      "id": "uuid",
                      "external_id": "job-4821",
                      "team_members": [
                        {
                          "id": "uuid",
                          "email": "tech.alex@example.com",
                          "name": "Alex Rivera"
                        }
                      ],
                      "starts_at": "2026-10-14T13:00:00.000Z",
                      "ends_at": "2026-10-14T16:30:00.000Z",
                      "title": "Job #4821 water heater install",
                      "source": "api",
                      "created_at": "2026-10-09T15:02:11Z",
                      "updated_at": "2026-10-09T15:02:11Z"
                    },
                    "created": true,
                    "changed": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_busy_block",
        "tags": [
          "Team busy times"
        ],
        "summary": "Remove a busy block",
        "description": "By your own id; the time opens up again at once. 404 when there is no block with that id.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "description": "Your id for the block (URL-encoded).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/busy-blocks": {
      "get": {
        "operationId": "list_busy_blocks",
        "tags": [
          "Team busy times"
        ],
        "summary": "List busy blocks",
        "description": "Blocks that overlap the window, earliest first. Default window: from yesterday, 60 days long; at most 366 days.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "team_member",
            "in": "query",
            "required": false,
            "description": "Only this person's blocks (user id or email).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO start with a zone.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO end with a zone.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-500, default 100.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many (has_more says whether there are more).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/busy-blocks/sync": {
      "post": {
        "operationId": "sync_busy_blocks",
        "tags": [
          "Team busy times"
        ],
        "summary": "Sync a time window in one call",
        "description": "Send your full list of busy blocks for a window: blocks in the list are added or replaced, and blocks you sent earlier that START inside [from, to) but are no longer in the list are removed (cancelled or moved jobs).\n\n- With `team_member`, only that person's blocks are replaced and each block defaults to them; a removed block that also names other people keeps them.\n- Up to 500 blocks per call.\n- Good for a nightly or hourly full sync next to the per-block calls.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "from": {
                    "type": "string",
                    "description": "Window start, ISO 8601 with a zone."
                  },
                  "to": {
                    "type": "string",
                    "description": "Window end; at most 366 days after from."
                  },
                  "team_member": {
                    "type": "string",
                    "description": "Sync one person only (user id or email)."
                  },
                  "blocks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ external_id, team_member | team_members, starts_at, ends_at, title? }]. [] clears the window."
                  }
                },
                "required": [
                  "workspace_id",
                  "from",
                  "to",
                  "blocks"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "from": "2026-10-13T00:00:00-05:00",
                "to": "2026-10-20T00:00:00-05:00",
                "team_member": "tech.alex@example.com",
                "blocks": [
                  {
                    "external_id": "job-4821",
                    "starts_at": "2026-10-14T08:00:00-05:00",
                    "ends_at": "2026-10-14T11:30:00-05:00"
                  },
                  {
                    "external_id": "pto-2210",
                    "starts_at": "2026-10-17T00:00:00-05:00",
                    "ends_at": "2026-10-18T00:00:00-05:00",
                    "title": "Day off"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "created": 1,
                    "updated": 0,
                    "unchanged": 1,
                    "removed": 2,
                    "window": {
                      "from": "2026-10-13T05:00:00.000Z",
                      "to": "2026-10-20T05:00:00.000Z"
                    },
                    "team_member": {
                      "id": "uuid",
                      "email": "tech.alex@example.com",
                      "name": "Alex Rivera"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/stages/{stage_id}": {
      "patch": {
        "operationId": "update_stage",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Rename, recolour or hide a stage",
        "description": "The five built-in stages (new, contacted, booked, won, lost) can only change label, color and hidden.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage_id",
            "in": "path",
            "required": true,
            "description": "Stage id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_stage",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Delete a custom stage",
        "description": "Its leads move to the stage named in `move_to`. Built-in stages cannot be deleted; hide them instead.\n\nRequired scope: `leads:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage_id",
            "in": "path",
            "required": true,
            "description": "Stage id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "move_to",
            "in": "query",
            "required": true,
            "description": "Key of the stage that takes over the leads.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/stages/reorder": {
      "post": {
        "operationId": "reorder_stages",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Reorder the pipeline",
        "description": "Required scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "order": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Every stage id of the sub-account, first to last."
                  }
                },
                "required": [
                  "workspace_id",
                  "order"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/pipelines": {
      "get": {
        "operationId": "list_pipelines",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "List the extra pipelines",
        "description": "Pipelines next to the main one (`GET /v1/stages`), each with its stages in order.\n\n- A stage's kind is open, won or lost; `lead_stage_key`, when set, is the main stage a deal's lead moves to when the deal lands there.\n- Needs More pipelines on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.pipelines`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "pipelines": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Projects",
                        "position": 0,
                        "stages": [
                          {
                            "id": "uuid",
                            "pipeline_id": "uuid",
                            "label": "Estimate sent",
                            "color": "blue",
                            "kind": "open",
                            "position": 0,
                            "lead_stage_key": null
                          },
                          {
                            "id": "uuid",
                            "pipeline_id": "uuid",
                            "label": "Done",
                            "color": "emerald",
                            "kind": "won",
                            "position": 1,
                            "lead_stage_key": "won"
                          },
                          {
                            "id": "uuid",
                            "pipeline_id": "uuid",
                            "label": "Lost",
                            "color": "rose",
                            "kind": "lost",
                            "position": 2,
                            "lead_stage_key": null
                          }
                        ],
                        "created_at": "2026-11-03T15:00:00Z",
                        "updated_at": "2026-11-03T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_pipeline",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Add a pipeline",
        "description": "Owners and admins. Without stages it starts with New, In progress, Won and Lost.\n\n- Up to 20 pipelines, 30 stages each; names are unique per sub-account.\n- Needs More pipelines on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.pipelines`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Its name (max 60)."
                  },
                  "stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Stages in order: {label, color, kind (open | won | lost), lead_stage_key}."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Projects",
                "stages": [
                  {
                    "label": "Estimate sent",
                    "kind": "open"
                  },
                  {
                    "label": "Done",
                    "kind": "won",
                    "lead_stage_key": "won"
                  },
                  {
                    "label": "Lost",
                    "kind": "lost"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "pipeline": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Projects",
                      "position": 0,
                      "stages": [
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Estimate sent",
                          "color": "blue",
                          "kind": "open",
                          "position": 0,
                          "lead_stage_key": null
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Done",
                          "color": "emerald",
                          "kind": "won",
                          "position": 1,
                          "lead_stage_key": "won"
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Lost",
                          "color": "rose",
                          "kind": "lost",
                          "position": 2,
                          "lead_stage_key": null
                        }
                      ],
                      "created_at": "2026-11-03T15:00:00Z",
                      "updated_at": "2026-11-03T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/pipelines/{pipeline_id}": {
      "patch": {
        "operationId": "update_pipeline",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Rename or move a pipeline",
        "description": "Required scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pipeline_id",
            "in": "path",
            "required": true,
            "description": "The pipeline.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "New name (max 60)."
                  },
                  "position": {
                    "type": "number",
                    "description": "Its place among the pipelines (0 first)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Jobs"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "pipeline": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Jobs",
                      "position": 0,
                      "stages": [
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Estimate sent",
                          "color": "blue",
                          "kind": "open",
                          "position": 0,
                          "lead_stage_key": null
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Done",
                          "color": "emerald",
                          "kind": "won",
                          "position": 1,
                          "lead_stage_key": "won"
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Lost",
                          "color": "rose",
                          "kind": "lost",
                          "position": 2,
                          "lead_stage_key": null
                        }
                      ],
                      "created_at": "2026-11-03T15:00:00Z",
                      "updated_at": "2026-11-03T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_pipeline",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Delete a pipeline",
        "description": "Its stages and deals are deleted. The leads stay, with their main pipeline stage.\n\nRequired scope: `leads:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pipeline_id",
            "in": "path",
            "required": true,
            "description": "The pipeline.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "deals_deleted": 12
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/pipelines/{pipeline_id}/stages": {
      "post": {
        "operationId": "create_pipeline_stage",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Add a stage to a pipeline",
        "description": "Required scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pipeline_id",
            "in": "path",
            "required": true,
            "description": "The pipeline.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Its name (max 40), unique in the pipeline."
                  },
                  "color": {
                    "type": "string",
                    "description": "Default slate.",
                    "enum": [
                      "blue",
                      "amber",
                      "violet",
                      "cyan",
                      "emerald",
                      "rose",
                      "teal",
                      "orange",
                      "pink",
                      "indigo",
                      "lime",
                      "slate"
                    ]
                  },
                  "kind": {
                    "type": "string",
                    "description": "open (still worked, the default), won or lost (closed, in the win rate).",
                    "enum": [
                      "open",
                      "won",
                      "lost"
                    ]
                  },
                  "lead_stage_key": {
                    "type": "string",
                    "description": "A main stage key (GET /v1/stages): a deal landing here moves its lead there too, like a click in the app. null = never."
                  },
                  "position": {
                    "type": "number",
                    "description": "Its place (0 first); default last."
                  }
                },
                "required": [
                  "label"
                ],
                "additionalProperties": true
              },
              "example": {
                "label": "Financing",
                "color": "amber",
                "kind": "open"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "pipeline": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Projects",
                      "position": 0,
                      "stages": [
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Estimate sent",
                          "color": "blue",
                          "kind": "open",
                          "position": 0,
                          "lead_stage_key": null
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Done",
                          "color": "emerald",
                          "kind": "won",
                          "position": 1,
                          "lead_stage_key": "won"
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Lost",
                          "color": "rose",
                          "kind": "lost",
                          "position": 2,
                          "lead_stage_key": null
                        }
                      ],
                      "created_at": "2026-11-03T15:00:00Z",
                      "updated_at": "2026-11-03T15:00:00Z"
                    },
                    "stage": {
                      "id": "uuid",
                      "pipeline_id": "uuid",
                      "label": "Estimate sent",
                      "color": "blue",
                      "kind": "open",
                      "position": 0,
                      "lead_stage_key": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/pipeline-stages/{stage_id}": {
      "patch": {
        "operationId": "update_pipeline_stage",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Change a pipeline stage",
        "description": "Send only what changes. Turning a stage won or lost closes the deals already in it; back to open reopens them.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage_id",
            "in": "path",
            "required": true,
            "description": "The stage (from GET /v1/pipelines).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "New name."
                  },
                  "color": {
                    "type": "string",
                    "description": "New colour.",
                    "enum": [
                      "blue",
                      "amber",
                      "violet",
                      "cyan",
                      "emerald",
                      "rose",
                      "teal",
                      "orange",
                      "pink",
                      "indigo",
                      "lime",
                      "slate"
                    ]
                  },
                  "kind": {
                    "type": "string",
                    "description": "open, won or lost.",
                    "enum": [
                      "open",
                      "won",
                      "lost"
                    ]
                  },
                  "lead_stage_key": {
                    "type": "string",
                    "description": "A main stage key, or null to stop moving leads."
                  },
                  "position": {
                    "type": "number",
                    "description": "Move it (0 first)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "lead_stage_key": "won"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "pipeline": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Projects",
                      "position": 0,
                      "stages": [
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Estimate sent",
                          "color": "blue",
                          "kind": "open",
                          "position": 0,
                          "lead_stage_key": null
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Done",
                          "color": "emerald",
                          "kind": "won",
                          "position": 1,
                          "lead_stage_key": "won"
                        },
                        {
                          "id": "uuid",
                          "pipeline_id": "uuid",
                          "label": "Lost",
                          "color": "rose",
                          "kind": "lost",
                          "position": 2,
                          "lead_stage_key": null
                        }
                      ],
                      "created_at": "2026-11-03T15:00:00Z",
                      "updated_at": "2026-11-03T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_pipeline_stage",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Delete a pipeline stage",
        "description": "A stage with deals needs `move_to_stage_id` (another stage of the same pipeline). A pipeline keeps at least one stage.\n\nRequired scope: `leads:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage_id",
            "in": "path",
            "required": true,
            "description": "The stage.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "move_to_stage_id",
            "in": "query",
            "required": false,
            "description": "Where its deals go.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "deals_moved": 3
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/deals": {
      "get": {
        "operationId": "list_deals",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "List deals",
        "description": "Deals in the extra pipelines, newest first, with their lead and stage.\n\n- A Technician (or limited Staff) key sees only the deals of their own leads.\n- Needs More pipelines on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.pipelines`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pipeline_id",
            "in": "query",
            "required": false,
            "description": "Only this pipeline.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage_id",
            "in": "query",
            "required": false,
            "description": "Only this stage.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "Only this lead's deals.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "open, closed, won or lost.",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "closed",
                "won",
                "lost"
              ]
            }
          },
          {
            "name": "external_id",
            "in": "query",
            "required": false,
            "description": "The deal with this outside id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-200, default 50.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deals": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "pipeline_id": "uuid",
                        "stage_id": "uuid",
                        "stage": {
                          "label": "Estimate sent",
                          "kind": "open"
                        },
                        "lead_id": "uuid",
                        "lead": {
                          "id": "uuid",
                          "full_name": "Murtaza N.",
                          "email": "murtaza@example.com",
                          "phone": "+14165550123"
                        },
                        "name": "Roof replacement",
                        "value_cents": 980000,
                        "assigned_to": null,
                        "external_id": null,
                        "status": "open",
                        "stage_entered_at": "2026-11-03T15:00:00Z",
                        "closed_at": null,
                        "created_at": "2026-11-03T15:00:00Z",
                        "updated_at": "2026-11-03T15:00:00Z"
                      }
                    ],
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_deal",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Put a lead in a pipeline",
        "description": "Owners and admins. Send `stage_id`, or `pipeline_id` to start in its first open stage. One lead can have several deals, even in the same pipeline. A stage with `lead_stage_key` moves the lead in the main pipeline too.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "The lead."
                  },
                  "stage_id": {
                    "type": "string",
                    "description": "Its stage."
                  },
                  "pipeline_id": {
                    "type": "string",
                    "description": "Instead of stage_id: start in this pipeline's first open stage."
                  },
                  "name": {
                    "type": "string",
                    "description": "What it is (max 120). Empty: the lead's name is shown."
                  },
                  "value_cents": {
                    "type": "number",
                    "description": "Its value in cents."
                  },
                  "assigned_to": {
                    "type": "string",
                    "description": "A team member's user id (GET /v1/members)."
                  },
                  "external_id": {
                    "type": "string",
                    "description": "Another system's id, unique per sub-account (409 when taken)."
                  }
                },
                "required": [
                  "workspace_id",
                  "lead_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_id": "uuid",
                "pipeline_id": "uuid",
                "name": "Roof replacement",
                "value_cents": 980000
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deal": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "pipeline_id": "uuid",
                      "stage_id": "uuid",
                      "stage": {
                        "label": "Estimate sent",
                        "kind": "open"
                      },
                      "lead_id": "uuid",
                      "lead": {
                        "id": "uuid",
                        "full_name": "Murtaza N.",
                        "email": "murtaza@example.com",
                        "phone": "+14165550123"
                      },
                      "name": "Roof replacement",
                      "value_cents": 980000,
                      "assigned_to": null,
                      "external_id": null,
                      "status": "open",
                      "stage_entered_at": "2026-11-03T15:00:00Z",
                      "closed_at": null,
                      "created_at": "2026-11-03T15:00:00Z",
                      "updated_at": "2026-11-03T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/deals/{deal_id}": {
      "get": {
        "operationId": "get_deal",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Get a deal",
        "description": "Required scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "deal_id",
            "in": "path",
            "required": true,
            "description": "The deal.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deal": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "pipeline_id": "uuid",
                      "stage_id": "uuid",
                      "stage": {
                        "label": "Estimate sent",
                        "kind": "open"
                      },
                      "lead_id": "uuid",
                      "lead": {
                        "id": "uuid",
                        "full_name": "Murtaza N.",
                        "email": "murtaza@example.com",
                        "phone": "+14165550123"
                      },
                      "name": "Roof replacement",
                      "value_cents": 980000,
                      "assigned_to": null,
                      "external_id": null,
                      "status": "open",
                      "stage_entered_at": "2026-11-03T15:00:00Z",
                      "closed_at": null,
                      "created_at": "2026-11-03T15:00:00Z",
                      "updated_at": "2026-11-03T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_deal",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Move or change a deal",
        "description": "`stage_id` moves it (any stage of the sub-account, so it can change pipeline). Moving into a won or lost stage closes it; a stage with `lead_stage_key` moves the lead too.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deal_id",
            "in": "path",
            "required": true,
            "description": "The deal.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stage_id": {
                    "type": "string",
                    "description": "Move it here."
                  },
                  "name": {
                    "type": "string",
                    "description": "What it is, or null."
                  },
                  "value_cents": {
                    "type": "number",
                    "description": "Its value in cents, or null."
                  },
                  "assigned_to": {
                    "type": "string",
                    "description": "A team member's user id, or null."
                  },
                  "external_id": {
                    "type": "string",
                    "description": "Another system's id, or null."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "stage_id": "uuid",
                "value_cents": 1050000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deal": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "pipeline_id": "uuid",
                      "stage_id": "uuid",
                      "stage": {
                        "label": "Estimate sent",
                        "kind": "open"
                      },
                      "lead_id": "uuid",
                      "lead": {
                        "id": "uuid",
                        "full_name": "Murtaza N.",
                        "email": "murtaza@example.com",
                        "phone": "+14165550123"
                      },
                      "name": "Roof replacement",
                      "value_cents": 1050000,
                      "assigned_to": null,
                      "external_id": null,
                      "status": "open",
                      "stage_entered_at": "2026-11-03T15:00:00Z",
                      "closed_at": null,
                      "created_at": "2026-11-03T15:00:00Z",
                      "updated_at": "2026-11-03T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_deal",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Take a deal out of its pipeline",
        "description": "The lead stays, with its main pipeline stage.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deal_id",
            "in": "path",
            "required": true,
            "description": "The deal.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/custom-fields": {
      "get": {
        "operationId": "list_custom_fields",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "List custom lead fields",
        "description": "Required scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_archived",
            "in": "query",
            "required": false,
            "description": "Include archived fields.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_custom_field",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Add a custom lead field",
        "description": "`field_key` and `field_type` cannot change later, because stored lead values depend on them.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "label": {
                    "type": "string",
                    "description": "Field label (max 80)."
                  },
                  "field_type": {
                    "type": "string",
                    "description": "Default text.",
                    "enum": [
                      "text",
                      "textarea",
                      "number",
                      "money",
                      "phone",
                      "email",
                      "select",
                      "date",
                      "datetime",
                      "url",
                      "boolean",
                      "rating",
                      "multiselect"
                    ]
                  },
                  "field_key": {
                    "type": "string",
                    "description": "Defaults to a key made from the label."
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Choices for select / multiselect."
                  },
                  "required": {
                    "type": "boolean",
                    "description": "Default false."
                  },
                  "show_in_list": {
                    "type": "boolean",
                    "description": "Show as a column in the leads list."
                  }
                },
                "required": [
                  "workspace_id",
                  "label"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "label": "Roof type",
                "field_type": "select",
                "options": [
                  "Shingle",
                  "Metal",
                  "Tile"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/custom-fields/{field_id}": {
      "patch": {
        "operationId": "update_custom_field",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Update a custom field",
        "description": "Send `archived: false` to restore an archived field.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "field_id",
            "in": "path",
            "required": true,
            "description": "Field id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "archive_custom_field",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Archive a custom field",
        "description": "Hides the field. Values already stored on leads are kept.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "field_id",
            "in": "path",
            "required": true,
            "description": "Field id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lead-routing": {
      "get": {
        "operationId": "get_lead_routing",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "Get lead routing (round robin, Grab it)",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_lead_routing",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "Set lead routing (round robin, Grab it)",
        "description": "How NEW LEADS are handed to team members.\n\n- Round robin assigns them in turn (a round-robin calendar is separate: it rotates appointment hosts): an empty `eligible_member_ids` list means everyone takes turns, and `member_weights` splits leads by percentage (80/20 gives one person 8 of every 10 leads, spread out); {} goes back to even turns.\n- Grab it (`grab_enabled`) puts a Grab it link in every new-lead alert, and the first person to tap it gets the lead.\n- Only one of the two is on at a time: turning one on turns the other off.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "round_robin_enabled": {
                    "type": "boolean",
                    "description": "Turn the rotation on or off."
                  },
                  "eligible_member_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "User ids from GET /v1/members. Empty = everyone."
                  },
                  "member_weights": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Percentage split by user id (GET /v1/members): {\"<user_id>\": 80, \"<other_user_id>\": 20}. Whole percents 0-100; the shares above 0 must add up to exactly 100. Sets eligible_member_ids to the people with a share and restarts the rotation. {} = even turns (keeps who is in the rotation)."
                  },
                  "notify_assignee_only": {
                    "type": "boolean",
                    "description": "Alert only the person the lead went to."
                  },
                  "skip_imported_leads": {
                    "type": "boolean",
                    "description": "Leave imported leads unassigned."
                  },
                  "notify_on_reply": {
                    "type": "boolean",
                    "description": "Alert the assignee when the lead replies."
                  },
                  "grab_enabled": {
                    "type": "boolean",
                    "description": "Grab it: a Grab it link in every new-lead alert; the first person to tap it gets the lead. Turns round robin off."
                  },
                  "grab_member_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Who can grab leads: user ids from GET /v1/members. Empty = everyone who works in the sub-account."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "round_robin_enabled": true,
                "member_weights": {
                  "user-uuid-a": 80,
                  "user-uuid-b": 20
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/alert-recipients": {
      "get": {
        "operationId": "list_alert_recipients",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "List who is alerted about new leads and AI receptionist calls",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_alert_recipient",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "Add a lead alert recipient",
        "description": "Lead details are sent to this phone or inbox, so this needs an admin-scoped key.\n\nRequired scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "channel": {
                    "type": "string",
                    "description": "sms or email.",
                    "enum": [
                      "sms",
                      "email"
                    ]
                  },
                  "destination": {
                    "type": "string",
                    "description": "Phone (US 10-digit or +country code; stored as E.164) or email address."
                  },
                  "label": {
                    "type": "string",
                    "description": "e.g. Owner's cell."
                  },
                  "notify_leads": {
                    "type": "boolean",
                    "description": "Gets new-lead, appointment and reply alerts. Default true."
                  },
                  "notify_calls": {
                    "type": "boolean",
                    "description": "Gets a summary after every AI receptionist call (who called, the outcome, any message or booking, the transcript). Default false."
                  },
                  "lead_sources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Lead alerts only about leads from these sources, e.g. [\"site_widget\"] for Website chat leads: meta_lead_ad, smart_form (started forms too), website_form, site_widget, webhook, api, instagram, messenger, sms_inbound, email_inbound, calendly, acuity, review_funnel, manual, import, other. [] = every lead (default). Call summaries are never filtered."
                  }
                },
                "required": [
                  "workspace_id",
                  "channel",
                  "destination"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "channel": "sms",
                "destination": "+14155550123",
                "label": "Owner"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/alert-recipients/{recipient_id}": {
      "patch": {
        "operationId": "update_alert_recipient",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "Update a lead alert recipient",
        "description": "Send any of label, destination, active, `notify_leads`, `notify_calls`, `lead_sources` ([] = every lead). A recipient keeps at least one of `notify_leads` or `notify_calls`.\n\nRequired scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recipient_id",
            "in": "path",
            "required": true,
            "description": "Recipient id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_alert_recipient",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "Remove a lead alert recipient",
        "description": "Required scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recipient_id",
            "in": "path",
            "required": true,
            "description": "Recipient id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lead-sources": {
      "get": {
        "operationId": "list_lead_sources",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "List lead source links",
        "description": "Each link is a private URL that accepts leads, so reading them takes write scope. Treat the URL as a secret.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_lead_source",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "Create a lead source link",
        "description": "Returns a URL any website form, landing page tool or CRM can POST leads (or appointments) to.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "e.g. Website contact form."
                  },
                  "field_mapping": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Their field name to ours: {\"Full Name\":\"full_name\",\"Roof size\":\"custom:roof_size\"}. Targets: full_name, or first_name and last_name (saved together as the lead's name), email, phone, address, city, state, zip, inquiry, notes, appointment_*, utm_source, utm_medium, utm_campaign, utm_term (ad set), utm_content (ad) or custom:<field_key>. A state is saved as its code (\"Texas\" becomes TX); utm_source sets the Leads page Source filter (\"meta_ads\" or \"facebook\" is Facebook)."
                  },
                  "default_source": {
                    "type": "string",
                    "description": "Source label stamped on these leads."
                  },
                  "default_status": {
                    "type": "string",
                    "description": "Default new."
                  },
                  "payload_kind": {
                    "type": "string",
                    "description": "Default auto. update = a form your own team fills in (e.g. during a call): its answers go onto the matching contact (lead_id, phone, then email; added quietly when nobody matches) and nothing is sent: no first text, team alert, Instant Lead Connect call or new-lead automation.",
                    "enum": [
                      "auto",
                      "lead",
                      "appointment",
                      "update"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Website contact form",
                "default_source": "Website",
                "field_mapping": {
                  "Your name": "full_name",
                  "Phone number": "phone"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lead-sources/{lead_source_id}": {
      "patch": {
        "operationId": "update_lead_source",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "Update a lead source link",
        "description": "Links created by an integration (for example Typeform) are managed there and answer 409.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_source_id",
            "in": "path",
            "required": true,
            "description": "Lead source id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_lead_source",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "Delete a lead source link",
        "description": "Required scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_source_id",
            "in": "path",
            "required": true,
            "description": "Lead source id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/outbound-webhooks": {
      "get": {
        "operationId": "list_outbound_webhooks",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "List outbound webhooks",
        "description": "Never returns signing secrets or auth tokens.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_outbound_webhook",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "Create an outbound webhook",
        "description": "Pushes lead and appointment events to another system (Zapier, Make, a CRM). Lead data leaves the account, so every write needs an admin-scoped key and `target_url` must be https on a public host. The signing secret is returned once.\n\nRequired scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "e.g. Zapier: new leads."
                  },
                  "target_url": {
                    "type": "string",
                    "description": "https:// URL that receives the POST."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Default lead.created and appointment.booked. See the sub-account webhook events list."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Default true."
                  },
                  "preset": {
                    "type": "string",
                    "description": "Payload flavour.",
                    "enum": [
                      "zapier",
                      "make",
                      "salesforce_flow",
                      "service_titan",
                      "custom"
                    ]
                  },
                  "auth_type": {
                    "type": "string",
                    "description": "Default none. Send auth_token (and auth_header_name or auth_username) with it. Write-only.",
                    "enum": [
                      "none",
                      "bearer",
                      "header",
                      "basic"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "name",
                  "target_url"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Zapier: new leads",
                "target_url": "https://hooks.zapier.com/hooks/catch/123/abc/",
                "events": [
                  "lead.created"
                ],
                "preset": "zapier"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/outbound-webhooks/{webhook_id}": {
      "patch": {
        "operationId": "update_outbound_webhook",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "Update an outbound webhook",
        "description": "Required scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "webhook_id",
            "in": "path",
            "required": true,
            "description": "Webhook id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_outbound_webhook",
        "tags": [
          "Lead sources & webhooks"
        ],
        "summary": "Delete an outbound webhook",
        "description": "Required scope: `workspaces:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "webhook_id",
            "in": "path",
            "required": true,
            "description": "Webhook id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/knowledge-base": {
      "get": {
        "operationId": "get_knowledge_base",
        "tags": [
          "AI agent"
        ],
        "summary": "Read the AI's FAQ",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_knowledge_base",
        "tags": [
          "AI agent"
        ],
        "summary": "Replace the AI's FAQ",
        "description": "The FAQ is what the AI texting agent and AI receptionist answer from. Max 200 entries (question 300 characters, answer 2000).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "entries": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ question, answer }]. Replaces the whole list."
                  }
                },
                "required": [
                  "workspace_id",
                  "entries"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_knowledge_base",
        "tags": [
          "AI agent"
        ],
        "summary": "Add FAQ entries",
        "description": "Merges into the existing list. The same question again replaces its answer.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "entries": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ question, answer }]."
                  }
                },
                "required": [
                  "workspace_id",
                  "entries"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "entries": [
                  {
                    "question": "Do you offer financing?",
                    "answer": "Yes, 0% for 12 months on approved credit."
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/photos": {
      "get": {
        "operationId": "list_brain_photos",
        "tags": [
          "AI agent"
        ],
        "summary": "AI Brain photos",
        "description": "Photos of the business's work the AI may text a customer who asks to see some (up to 100): link, caption, the service it shows, on / off, how often it was sent.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "description": "Only on (true) or off (false).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_brain_photo",
        "tags": [
          "AI agent"
        ],
        "summary": "Add an AI Brain photo",
        "description": "From a public link to a JPEG, PNG or WebP (10 MB at most), stored like an upload on the page. The AI writes the caption and service you leave out, which is how it picks the right photo. 409 at 100 photos.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "image_url": {
                    "type": "string",
                    "description": "Public link to the image."
                  },
                  "caption": {
                    "type": "string",
                    "description": "What it shows (max 300)."
                  },
                  "service": {
                    "type": "string",
                    "description": "The service (max 80), e.g. Roof repair."
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "required": [
                  "workspace_id",
                  "image_url"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "image_url": "https://example.com/jobs/roof-after.jpg",
                "service": "Roof repair"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/photos/{photo_id}": {
      "patch": {
        "operationId": "update_brain_photo",
        "tags": [
          "AI agent"
        ],
        "summary": "Change an AI Brain photo",
        "description": "Required scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "photo_id",
            "in": "path",
            "required": true,
            "description": "Photo id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "caption": {
                    "type": "string",
                    "description": "What it shows (max 300)."
                  },
                  "service": {
                    "type": "string",
                    "description": "The service it shows (max 80)."
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Off: the AI stops sending it."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_brain_photo",
        "tags": [
          "AI agent"
        ],
        "summary": "Remove an AI Brain photo",
        "description": "Required scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "photo_id",
            "in": "path",
            "required": true,
            "description": "Photo id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/prices": {
      "get": {
        "operationId": "list_brain_prices",
        "tags": [
          "AI agent"
        ],
        "summary": "AI Brain prices",
        "description": "The services and products the AI may quote in texts, emails, chat and on calls (up to 300), each with `price_text` as the AI says it, plus `note` (what it says with prices) and `currency`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_price_book",
            "in": "query",
            "required": false,
            "description": "Also the invoice Price book items the AI isn't using (ai_enabled false).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "items": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Spring replacement",
                        "kind": "service",
                        "category": "Repairs",
                        "description": "Both springs, labor included.",
                        "price_type": "from",
                        "unit_price_cents": 25000,
                        "price_max_cents": null,
                        "price_unit": null,
                        "price_text": "From $250",
                        "taxable": true,
                        "ai_enabled": true,
                        "is_active": true,
                        "usage_count": 12,
                        "created_at": "2026-11-10T00:00:00Z",
                        "updated_at": "2026-11-10T00:00:00Z"
                      }
                    ],
                    "note": "Prices don't include tax.",
                    "currency": "usd",
                    "limit": 300
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_brain_prices",
        "tags": [
          "AI agent"
        ],
        "summary": "Add AI Brain prices",
        "description": "One item, or `items` with up to 100. A name already in the Price book changes that item instead of adding a twin, and puts it on the AI's list. Prices are in cents. 409 past 300 items.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Several at once: each takes the fields below."
                  },
                  "name": {
                    "type": "string",
                    "description": "What it is (max 120)."
                  },
                  "kind": {
                    "type": "string",
                    "description": "service (default) or product."
                  },
                  "category": {
                    "type": "string",
                    "description": "A group for it (max 60)."
                  },
                  "description": {
                    "type": "string",
                    "description": "What's included, sizes, conditions (max 500)."
                  },
                  "price_type": {
                    "type": "string",
                    "description": "fixed (default), from, range or quote (no set price)."
                  },
                  "unit_price_cents": {
                    "type": "number",
                    "description": "The price, or the bottom of a range, in cents. Required unless quote."
                  },
                  "price_max_cents": {
                    "type": "number",
                    "description": "The top of a range, in cents."
                  },
                  "price_unit": {
                    "type": "string",
                    "description": "e.g. per hour, each (max 30)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "items": [
                  {
                    "name": "Spring replacement",
                    "category": "Repairs",
                    "price_type": "from",
                    "unit_price_cents": 25000
                  },
                  {
                    "name": "Custom door",
                    "price_type": "quote"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/prices/{item_id}": {
      "patch": {
        "operationId": "update_brain_price",
        "tags": [
          "AI agent"
        ],
        "summary": "Change an AI Brain price",
        "description": "Any field. `ai_enabled: true` puts an invoice Price book item on the AI's list.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item_id",
            "in": "path",
            "required": true,
            "description": "Item id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "What it is (max 120)."
                  },
                  "kind": {
                    "type": "string",
                    "description": "service or product."
                  },
                  "category": {
                    "type": "string",
                    "description": "A group for it (max 60)."
                  },
                  "description": {
                    "type": "string",
                    "description": "What's included (max 500)."
                  },
                  "price_type": {
                    "type": "string",
                    "description": "fixed, from, range or quote."
                  },
                  "unit_price_cents": {
                    "type": "number",
                    "description": "The price, or the bottom of a range, in cents."
                  },
                  "price_max_cents": {
                    "type": "number",
                    "description": "The top of a range, in cents."
                  },
                  "price_unit": {
                    "type": "string",
                    "description": "e.g. per hour (max 30)."
                  },
                  "ai_enabled": {
                    "type": "boolean",
                    "description": "On the AI's list or not."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "remove_brain_price",
        "tags": [
          "AI agent"
        ],
        "summary": "Stop the AI quoting a price",
        "description": "Takes it off the AI's list. It stays in the Price book for invoices and estimates.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item_id",
            "in": "path",
            "required": true,
            "description": "Item id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/prices/note": {
      "put": {
        "operationId": "set_brain_price_note",
        "tags": [
          "AI agent"
        ],
        "summary": "What the AI says with prices",
        "description": "For example, that prices don't include tax. Empty clears it.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "note": {
                    "type": "string",
                    "description": "Max 1000 characters."
                  }
                },
                "required": [
                  "workspace_id",
                  "note"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "note": "Prices don't include tax."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/waiting": {
      "get": {
        "operationId": "list_brain_waiting",
        "tags": [
          "AI agent"
        ],
        "summary": "Questions waiting on you",
        "description": "AI Brain > Waiting on you: questions customers asked (texts, chat, DMs, calls) that the AI couldn't answer and handed to the team, newest first, one row per question (times = how many customers asked, variants = how they wrote it). Answered and dismissed ones are left out.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "waiting": [
                      {
                        "event_id": "uuid",
                        "event_ids": [
                          "uuid",
                          "uuid"
                        ],
                        "variants": [
                          "Do you work on Sundays?",
                          "Are you open Sunday?"
                        ],
                        "lead_id": "uuid",
                        "lead_name": "Jane Doe",
                        "question": "Do you work on Sundays?",
                        "asked_at": "2026-10-24T18:02:00Z",
                        "times": 2,
                        "channel": "sms"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/waiting/answer": {
      "post": {
        "operationId": "answer_brain_waiting",
        "tags": [
          "AI agent"
        ],
        "summary": "Answer a waiting question",
        "description": "As Answer it on the page: the answer becomes a saved answer (replacing one to the same question) that the AI texter and receptionist use from now on, the question leaves the list, and the AI turns back on for the leads it was paused on for that question. Nothing is sent to the customer.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "question": {
                    "type": "string",
                    "description": "The question as listed."
                  },
                  "answer": {
                    "type": "string",
                    "description": "What the AI should say (max 2000)."
                  },
                  "event_id": {
                    "type": "string",
                    "description": "The row's event_id."
                  }
                },
                "required": [
                  "workspace_id",
                  "question",
                  "answer"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "event_id": "uuid",
                "question": "Do you work on Sundays?",
                "answer": "No, we're open Monday to Saturday, 8 to 6."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "saved": true,
                    "ok": true,
                    "replaced": false,
                    "entries": 18,
                    "resumed_lead_ids": [
                      "uuid"
                    ],
                    "still_waiting": 0
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-brain/waiting/dismiss": {
      "post": {
        "operationId": "dismiss_brain_waiting",
        "tags": [
          "AI agent"
        ],
        "summary": "Dismiss waiting questions",
        "description": "Takes questions off the list without teaching the AI (it still treats them as open); undo: true puts them back.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "event_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The rows' event_ids."
                  },
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Or the questions themselves."
                  },
                  "undo": {
                    "type": "boolean",
                    "description": "Put them back."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-receptionist": {
      "get": {
        "operationId": "get_ai_receptionist",
        "tags": [
          "AI agent"
        ],
        "summary": "Read the AI receptionist settings",
        "description": "Also returns the list of voices, and `collect_fields` as a list of keys.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_ai_receptionist",
        "tags": [
          "AI agent"
        ],
        "summary": "Configure the AI receptionist",
        "description": "The AI that answers the sub-account's phone. Answered calls bill 1.5 credits per minute of AI conversation (15-second steps; time after a transfer to a person bills as phone minutes), and it needs a phone number on the sub-account to do anything (the response carries a warning when there is none).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Turn it on or off."
                  },
                  "mode": {
                    "type": "string",
                    "description": "Every call, or only outside business hours.",
                    "enum": [
                      "always",
                      "after_hours"
                    ]
                  },
                  "goal": {
                    "type": "string",
                    "description": "What it tries to do.",
                    "enum": [
                      "book",
                      "support",
                      "book_and_support"
                    ]
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "Max 40."
                  },
                  "voice": {
                    "type": "string",
                    "description": "One of the voices returned by GET."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "Max 400."
                  },
                  "after_hours_greeting": {
                    "type": "string",
                    "description": "Max 400."
                  },
                  "extra_instructions": {
                    "type": "string",
                    "description": "Max 1200."
                  },
                  "transfer_enabled": {
                    "type": "boolean",
                    "description": "Allow transfers to a person."
                  },
                  "transfer_numbers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 8 phone numbers."
                  },
                  "take_messages": {
                    "type": "boolean",
                    "description": "Take a message when nobody is available."
                  },
                  "max_call_seconds": {
                    "type": "number",
                    "description": "60-1800."
                  },
                  "record_calls": {
                    "type": "boolean",
                    "description": "Record answered calls (billed per recorded minute)."
                  },
                  "update_contact_details": {
                    "type": "boolean",
                    "description": "Let it save the caller's name, email and address to the lead."
                  },
                  "collect_fields": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Details it asks for before booking: \"full_name\", \"phone\", \"email\", \"address\" or custom field keys (GET /v1/custom-fields). Max 12."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "enabled": true,
                "mode": "after_hours",
                "goal": "book_and_support",
                "agent_name": "Ava",
                "collect_fields": [
                  "address",
                  "roof_type"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}": {
      "get": {
        "operationId": "get_smart_form",
        "tags": [
          "Smart forms"
        ],
        "summary": "Get one smart form, whole",
        "description": "Everything about one form, to read before changing it: the basics, questions, qualifier questions, fields, qualification, estimate and hidden fields (as `POST /v1/smart-forms` takes them), design (every Design tab setting with its current value), screens (flow, `thank_you`, `disqualified_page`), `logo_url`, `favicon_url`, `offer_ids`, views, submissions, `public_url`, and embed: snippet (a container plus the loader script, the recommended way to put it on a website), iframe (for site builders that strip scripts) and `script_url`.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `smart_forms:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "smart_form": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Free roof inspection",
                      "slug": "free-roof-inspection-x7k2",
                      "is_published": true,
                      "layout_mode": "funnel",
                      "headline": "Get a free roof inspection",
                      "design": {
                        "font": "inter",
                        "heading_font": "match",
                        "background": "soft",
                        "radius": "rounded",
                        "button_style": "solid",
                        "accent": null,
                        "hero_image": null
                      },
                      "screens": {
                        "flow": {
                          "welcome": {
                            "enabled": true,
                            "cta_label": "Start",
                            "note": null
                          }
                        },
                        "thank_you": {
                          "headline": "Thanks! We'll call you shortly."
                        },
                        "disqualified_page": {}
                      },
                      "views": 412,
                      "submissions": 37,
                      "public_url": "https://crm.example.com/f/free-roof-inspection-x7k2",
                      "embed": {
                        "snippet": "<div data-usezu-form=\"https://crm.example.com/f/free-roof-inspection-x7k2\" ...></div>\n<script async src=\"https://crm.example.com/embed/smart-form.js?v=3\"></script>",
                        "iframe": "<iframe src=\"...\"></iframe>",
                        "script_url": "https://crm.example.com/embed/smart-form.js?v=3"
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_smart_form",
        "tags": [
          "Smart forms"
        ],
        "summary": "Delete a smart form",
        "description": "Deletes the form; its link and embeds stop working. A form with submissions answers 409 (`details.code` `needs_confirm`) until confirm=true is sent: the submission records are deleted with it, the leads they made stay. Cannot be undone.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "confirm",
            "in": "query",
            "required": false,
            "description": "true to delete a form that has submissions.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_smart_form",
        "tags": [
          "Smart forms"
        ],
        "summary": "Update or publish a smart form",
        "description": "Takes the same fields as create; send only what changes. questions, `qualifier_questions` and `hidden_fields` replace their lists; qualification, estimate, fields and `fields.address.service_area` are merged.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "is_published": {
                    "type": "boolean",
                    "description": "Publish or unpublish."
                  },
                  "layout_mode": {
                    "type": "string",
                    "description": "single_step, multi_step, conversational or funnel (see create).",
                    "enum": [
                      "single_step",
                      "multi_step",
                      "conversational",
                      "funnel"
                    ]
                  },
                  "qualifier_enabled": {
                    "type": "boolean",
                    "description": "Ask the qualifier_questions first."
                  },
                  "qualifier_questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the list (see create)."
                  },
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the list (see create)."
                  },
                  "qualification": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Merged (see create)."
                  },
                  "estimate": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Merged (see create)."
                  },
                  "calendar_routing": {
                    "type": "boolean",
                    "description": "Pick the calendar from the answers (see create)."
                  },
                  "fields": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Merged, including address.service_area (see create)."
                  },
                  "video": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The video at the top, merged (see create); null turns it off."
                  },
                  "hidden_fields": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the list (see create); null or [] clears it."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "fields": {
                  "address": {
                    "service_area": {
                      "enabled": true,
                      "mode": "radius",
                      "center": {
                        "lat": 32.7767,
                        "lng": -96.797,
                        "label": "Dallas, TX"
                      },
                      "radius_miles": 50
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/design": {
      "patch": {
        "operationId": "update_smart_form_design",
        "tags": [
          "Smart forms"
        ],
        "summary": "Change a smart form's design",
        "description": "The builder's Design tab. Send only what changes; null puts a setting back to its default; a value that isn't allowed is refused with the allowed ones.\n\nPick-one settings:\n- font and `heading_font` (system, inter, poppins, manrope, outfit, figtree, rubik, montserrat, raleway, urbanist, sora, lexend, archivo, barlow, karla, bricolage, bebas, anton, syne, clash, oswald, playfair, lora, cormorant, fraunces, merriweather; `heading_font` also takes match)\n- background (plain, soft, gradient, dark, spotlight)\n- radius (sharp, soft, rounded, pill)\n- hero (centered, left, compact)\n- card (flat, bordered, elevated)\n- scale (compact, normal, large, xl)\n- `heading_weight` (normal, semibold, bold, black)\n- `heading_tracking` (tight, normal, wide)\n- `button_style` (solid, gradient, outline, soft)\n- `button_size` (sm, md, lg)\n- `field_style` (outline, filled, underline)\n- density (compact, comfortable, spacious)\n- width (narrow, normal, wide)\n- `hero_overlay` (none, light, dark, heavy, gradient)\n- `hero_text` (auto, light, dark)\n- `headline_size` (auto, small, medium, large)\n\nColors: `primary_color`, accent, `hero_overlay_color` (#rrggbb).\n\nPictures (https links):\n- `logo_url`, `favicon_url`, `hero_image`\n- `logo_size` 32-160\n- `hero_blur` 0-2\n\n- Words: `hero_eyebrow`, `hero_badge`, `hero_note`, `submit_note`, `details_heading`, `footer_note`.\n- Switches: `show_logo`, `steps_hint`, `details_heading_on`, `section_numbers`.\n- Page sections under the form: features { enabled, title, items: [`{ icon, title, body, image_url }`] } (up to 6; icons: check, dollar, bolt, home, shield, clock, star, phone, calendar, wrench, sun, leaf, heart, truck, award, users), reviews { enabled, title, subtitle, items: [`{ quote, name, rating, image_url }`] } (up to 6: real customers' own words only) and cta `{ enabled, headline, subheadline, button_label }`; each merges, and its items replace the list.\n- The video at the top is `PATCH /v1/smart-forms/{form_id}` (video).\n- Answers the whole form.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "font": {
                    "type": "string",
                    "description": "Body font."
                  },
                  "background": {
                    "type": "string",
                    "description": "plain, soft, gradient, dark or spotlight."
                  },
                  "primary_color": {
                    "type": "string",
                    "description": "Brand color, #rrggbb."
                  },
                  "hero_image": {
                    "type": "string",
                    "description": "https link to the hero photo; null removes it."
                  },
                  "features": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The features section (merged)."
                  },
                  "reviews": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The reviews section (merged)."
                  },
                  "cta": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The closing call to action (merged)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "font": "poppins",
                "background": "dark",
                "radius": "pill",
                "button_style": "gradient",
                "primary_color": "#16a34a",
                "hero_badge": "Rated 4.9 by 300+ homeowners",
                "features": {
                  "enabled": true,
                  "title": "Why homeowners pick us",
                  "items": [
                    {
                      "icon": "shield",
                      "title": "Licensed and insured",
                      "body": "Every crew, every job."
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/screens": {
      "patch": {
        "operationId": "update_smart_form_screens",
        "tags": [
          "Smart forms"
        ],
        "summary": "Change a smart form's screens",
        "description": "The words and behaviour of the screens around the questions (the builder's Screens tab).\n\nSend only what changes; null puts a setting back to its default.\n\nflow:\n- welcome `{ enabled, cta_label, note }`\n- contact `{ eyebrow, headline, subheadline, consent_label, consent_required }`\n- booking `{ eyebrow, headline }`\n- name `{ first (ask for their name on its own screen first), headline, subheadline }`\n- progress (both, bar, counter, none)\n- transition (slide, fade, none)\n- `question_numbers`\n- `keyboard_hints`\n- `recall_name`\n- `auto_advance`\n- media `{ url, position: left | right }` (the picture or video beside a conversational form)\n- `question_images` `{ <question key>: https link }` (replaces the map)\n- `footer_links` [`{ label, url }`] (up to 4, replaces the list)\n\n- `thank_you`: headline, subheadline, `cta_label`, `cta_url`, `show_calendar_links`, `calendar_description`.\n- `disqualified_page` (who the form screens out lands here): headline, subheadline, `cta_label`, `cta_url`.\n- The questions themselves are `PATCH /v1/smart-forms/{form_id}` (questions, `qualifier_questions`).\n- Answers the whole form.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "flow": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Welcome, contact, booking and name screens, progress, pictures, footer links (merged)."
                  },
                  "thank_you": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The thank-you page (merged)."
                  },
                  "disqualified_page": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The page for people the form screens out (merged)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "flow": {
                  "welcome": {
                    "enabled": true,
                    "cta_label": "Get my quote"
                  },
                  "name": {
                    "first": true
                  }
                },
                "thank_you": {
                  "headline": "You're booked in",
                  "subheadline": "We'll text you a confirmation in a minute.",
                  "show_calendar_links": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/duplicate": {
      "post": {
        "operationId": "duplicate_smart_form",
        "tags": [
          "Smart forms"
        ],
        "summary": "Duplicate a smart form",
        "description": "A copy in the same sub-account with every setting, question, design, screen and offer of the original, a new link, unpublished, with no views or submissions. name is optional (default \"<name> (copy)\"). Copying into another sub-account stays in the app.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The copy's name."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Free roof inspection (storm season)"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/invoices": {
      "post": {
        "operationId": "create_invoice",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Create an invoice (draft)",
        "description": "A draft invoice, numbered like the app's: for a lead (`lead_id` fills in the customer and is needed to send it) or a `customer_name`, with its lines.\n\n- Tax, due date, terms, notes and card payments default to the sub-account's invoice settings; a `tax_rate` sent is one plain tax in place of them, or send taxes for named ones (GST + QST), each on its own line with the registration number from the settings.\n- Totals are worked out as the editor does: each line rounded, `discount_cents` off the subtotal (never more than it) and spread over the taxable lines, each tax rounded on its own.\n- `deposit_percent` or `deposit_cents` makes it a deposit invoice: it lists the whole job and `total_cents` is the deposit asked for now.\n- Card payment pages are set up in the app.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "Who it is for (fills in the customer; needed to send it). Or customer_name."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The lines, 1-100: [{ description (the line's name, max 300), quantity? (above 0, default 1), unit_price_cents (whole cents; below zero for a credit line), taxable? (default true) }]."
                  },
                  "tax_rate": {
                    "type": "number",
                    "description": "One tax, percent 0-30. Default: the sub-account's taxes."
                  },
                  "taxes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Instead of tax_rate, up to 4 named taxes: [{ name, rate }], e.g. GST 5 + QST 9.975."
                  },
                  "discount_cents": {
                    "type": "number",
                    "description": "Off the subtotal, whole cents. Default 0."
                  },
                  "deposit_percent": {
                    "type": "number",
                    "description": "Ask for this percent of the job now (above 0, up to 100). Or deposit_cents."
                  },
                  "deposit_cents": {
                    "type": "number",
                    "description": "Ask for this amount now, whole cents."
                  },
                  "due_date": {
                    "type": "string",
                    "description": "YYYY-MM-DD, or null for no due date. Default: the sub-account's due days from today."
                  },
                  "due_days": {
                    "type": "number",
                    "description": "Instead of due_date: due this many days from today (0-365)."
                  },
                  "issue_date": {
                    "type": "string",
                    "description": "YYYY-MM-DD, default today."
                  },
                  "notes": {
                    "type": "string",
                    "description": "A note to the customer (max 4000). Default: the sub-account's."
                  },
                  "terms": {
                    "type": "string",
                    "description": "Max 4000. Default: the sub-account's."
                  },
                  "currency": {
                    "type": "string",
                    "description": "3 letters. Default: the sub-account's."
                  },
                  "collect_payment": {
                    "type": "boolean",
                    "description": "Whether the customer may pay by card once a payment page is set up in the app. Default: the sub-account's."
                  },
                  "customer_name": {
                    "type": "string",
                    "description": "Without a lead, or to change what the lead fills in."
                  },
                  "customer_email": {
                    "type": "string",
                    "description": "Customer email."
                  },
                  "customer_phone": {
                    "type": "string",
                    "description": "Customer phone."
                  },
                  "customer_address": {
                    "type": "string",
                    "description": "Customer address."
                  }
                },
                "required": [
                  "workspace_id",
                  "items"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_id": "uuid",
                "items": [
                  {
                    "description": "Garage door opener",
                    "unit_price_cents": 49900
                  },
                  {
                    "description": "Labor",
                    "quantity": 2,
                    "unit_price_cents": 7500,
                    "taxable": false
                  }
                ],
                "discount_cents": 1000,
                "due_days": 7
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "invoice": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "lead_id": "uuid",
                      "number": "INV-000125",
                      "status": "draft",
                      "effective_status": "draft",
                      "kind": "invoice",
                      "currency": "usd",
                      "issue_date": "2026-11-15",
                      "due_date": "2026-11-22",
                      "customer_name": "Dana Fox",
                      "subtotal_cents": 64900,
                      "discount_cents": 1000,
                      "tax_rate": 8,
                      "taxes": [],
                      "tax_cents": 3930,
                      "total_cents": 67830,
                      "amount_paid_cents": 0,
                      "balance_cents": 67830,
                      "deposit_percent": null,
                      "deposit_cents": 0,
                      "public_path": null,
                      "items": [
                        {
                          "id": "uuid",
                          "description": "Garage door opener",
                          "quantity": 1,
                          "unit_price_cents": 49900,
                          "taxable": true,
                          "position": 0
                        }
                      ],
                      "events": [
                        {
                          "id": "uuid",
                          "event_type": "created",
                          "detail": "Invoice INV-000125 created through the API",
                          "created_at": "2026-11-15T10:00:00Z"
                        }
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "list_invoices",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Invoices (read only)",
        "description": "The sub-account's invoices, newest first. `effective_status` adds overdue (sent and past due), as the app shows it.\n\n- kind is invoice, deposit (it lists the whole job but asks only for `deposit_cents` now; `deposit_percent` when it was a percent) or balance (made by Bill the balance: `deposit_invoice_id` is the deposit it follows and `deposit_applied_cents` comes off the job total).\n- `total_cents` is always what this invoice asks for.\n- Payment processor details are never returned.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "sent",
                "paid",
                "void",
                "overdue"
              ]
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "One lead's invoices.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "invoices": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "lead_id": "uuid",
                        "number": "INV-000042",
                        "status": "sent",
                        "currency": "usd",
                        "issue_date": "2026-09-20",
                        "due_date": "2026-09-27",
                        "customer_name": "Jane Doe",
                        "customer_email": "jane@example.com",
                        "customer_phone": "+14155550123",
                        "total_cents": 125000,
                        "amount_paid_cents": 0,
                        "collect_payment": true,
                        "payment_gateway": "stripe",
                        "sent_at": "2026-09-20T15:00:00Z",
                        "viewed_at": null,
                        "paid_at": null,
                        "created_at": "2026-09-20T14:55:00Z",
                        "updated_at": "2026-09-20T15:00:00Z",
                        "effective_status": "overdue",
                        "balance_cents": 125000
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/invoices/{invoice_id}": {
      "patch": {
        "operationId": "update_invoice",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Change an invoice",
        "description": "Send only what changes. items replace every line, as the editor saves; new lines, taxes, a discount or a deposit work the totals out again (a percent deposit follows the new total, an amount stays).\n\n- `lead_id`: null unlinks it; a new lead fills in the customer unless you send the details.\n- `deposit_percent`: null takes a deposit away.\n- An invoice that has been paid (in full or in part) answers 409: make a new one.\n- One that already has a hosted card payment page for its amount answers 409 on anything that changes the amount: change it in the app, which makes the page again.\n- A balance invoice (billed after a deposit) keeps its currency and can't ask for another deposit.\n\nWho can call it: Owners and admins.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoice id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lead_id": {
                    "type": "string",
                    "description": "Who it is for, or null."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces every line: [{ description, quantity?, unit_price_cents, taxable? }]."
                  },
                  "tax_rate": {
                    "type": "number",
                    "description": "One tax, percent 0-30, in place of the invoice's taxes."
                  },
                  "taxes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Named taxes in place of the invoice's: [{ name, rate }]."
                  },
                  "discount_cents": {
                    "type": "number",
                    "description": "Off the subtotal, whole cents."
                  },
                  "deposit_percent": {
                    "type": "number",
                    "description": "Ask for this percent now, or null for no deposit."
                  },
                  "deposit_cents": {
                    "type": "number",
                    "description": "Ask for this amount now."
                  },
                  "due_date": {
                    "type": "string",
                    "description": "YYYY-MM-DD, or null. Or due_days."
                  },
                  "due_days": {
                    "type": "number",
                    "description": "Due this many days from today (0-365)."
                  },
                  "issue_date": {
                    "type": "string",
                    "description": "YYYY-MM-DD."
                  },
                  "notes": {
                    "type": "string",
                    "description": "A note to the customer, or null."
                  },
                  "terms": {
                    "type": "string",
                    "description": "Terms, or null."
                  },
                  "currency": {
                    "type": "string",
                    "description": "3 letters."
                  },
                  "collect_payment": {
                    "type": "boolean",
                    "description": "Whether the customer may pay by card."
                  },
                  "customer_name": {
                    "type": "string",
                    "description": "Customer name."
                  },
                  "customer_email": {
                    "type": "string",
                    "description": "Customer email."
                  },
                  "customer_phone": {
                    "type": "string",
                    "description": "Customer phone."
                  },
                  "customer_address": {
                    "type": "string",
                    "description": "Customer address."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "items": [
                  {
                    "description": "Garage door opener",
                    "unit_price_cents": 49900
                  },
                  {
                    "description": "Trip fee",
                    "unit_price_cents": 7500
                  }
                ],
                "discount_cents": 0
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_invoice",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Delete an invoice",
        "description": "The Invoices list's Delete: the invoice goes with its lines and history, and its customer link stops working. An invoice that has been paid (in full or in part) is a record and answers 409.\n\nWho can call it: Owners and admins.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoice id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "number": "INV-000125"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "get_invoice",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "One invoice with its line items and history",
        "description": "Adds the customer's address, notes, terms, subtotal, discount and tax, the PDF link, line items, the event history (created, sent, viewed, paid) and `public_path`, the customer's view-and-pay page on the sub-account's domain (none for drafts).\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoice id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/invoices/{invoice_id}/send": {
      "post": {
        "operationId": "send_invoice",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Send an invoice to the lead",
        "description": "Like the editor's Send: a text and/or an email to the invoice's lead with the link to view it (on the sub-account's own domain when it has one), in the editor's own words unless you send message (it must include `{link}`).\n\n- When the app already set up card payment for this invoice, the pay link rides along.\n- Sent as the key's person, with the usual opt-out, credit and limit checks; each is billed like any text or email.\n- A draft becomes sent; sending a sent one again is a re-send.\n- sent lists each channel and why one didn't go.\n- Needs a lead (PATCH `lead_id`) and at least one line; a paid invoice answers 409.\n- The email carries the link, not a PDF attachment (the app's Send attaches one).\n\nWho can call it: Owners and admins.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoice id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "description": "Default both (whichever the lead has).",
                    "enum": [
                      "sms",
                      "email",
                      "both"
                    ]
                  },
                  "message": {
                    "type": "string",
                    "description": "Your own wording, with {link} (max 1500)."
                  },
                  "subject": {
                    "type": "string",
                    "description": "The email's subject."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "channel": "sms"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sent": [
                      {
                        "channel": "sms",
                        "ok": true
                      }
                    ],
                    "link": "https://book.acme.com/i/abc123",
                    "status": "sent"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/invoices/{invoice_id}/mark-paid": {
      "post": {
        "operationId": "mark_invoice_paid",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Mark an invoice paid",
        "description": "The Invoices list's Mark as paid, for money taken outside the app (cash, a check, a transfer): the invoice becomes paid in full, now (on a deposit invoice, the deposit).\n\n- Whatever follows a paid invoice in the app follows this too.\n- Already paid answers 409.\n- No body.\n\nWho can call it: Owners and admins.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoice id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "invoice": {
                      "id": "uuid",
                      "number": "INV-000125",
                      "status": "paid",
                      "effective_status": "paid",
                      "total_cents": 67830,
                      "amount_paid_cents": 67830,
                      "balance_cents": 0,
                      "paid_at": "2026-11-15T10:05:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/custom-values": {
      "get": {
        "operationId": "list_custom_values",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "List custom values",
        "description": "Settings > Custom values: the business's own words used across every text, email and automation (a webinar date, a booking link, a promo code).\n\n- Each has a key, and token is what to paste into a message: `{{custom_values.<key>}}`.\n- Change a value and every message that names it says the new thing on its next send.\n- Different from custom fields, which hold one answer per lead.\n\nWho can call it: Any member.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "custom_values": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "key": "webinar_date",
                        "name": "Webinar date",
                        "value": "June 3 at 6 PM",
                        "folder": "Events",
                        "sort_order": 0,
                        "created_at": "2026-11-14T15:00:00Z",
                        "updated_at": "2026-11-14T15:00:00Z",
                        "token": "{{custom_values.webinar_date}}"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_custom_value",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Add a custom value",
        "description": "The key comes from the name (\"Webinar date\" becomes `webinar_date`; a taken one gets _2, _3 ...) unless you send key, which must be free (409 otherwise). A sub-account keeps up to 500.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "What the team calls it, up to 120 characters."
                  },
                  "value": {
                    "type": "string",
                    "description": "What messages say, up to 5,000 characters. Kept exactly as sent."
                  },
                  "folder": {
                    "type": "string",
                    "description": "A folder to keep it in, up to 60 characters."
                  },
                  "key": {
                    "type": "string",
                    "description": "The key in {{custom_values.<key>}}: lowercase letters, numbers and underscores, up to 64. Left out, it comes from the name."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Webinar date",
                "value": "June 3 at 6 PM",
                "folder": "Events"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "custom_value": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "key": "webinar_date",
                      "name": "Webinar date",
                      "value": "June 3 at 6 PM",
                      "folder": "Events",
                      "sort_order": 0,
                      "created_at": "2026-11-14T15:00:00Z",
                      "updated_at": "2026-11-14T15:00:00Z",
                      "token": "{{custom_values.webinar_date}}"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/custom-values/{value_id}": {
      "patch": {
        "operationId": "update_custom_value",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Change a custom value",
        "description": "Send what changes. Messages that name it say the new value on their next send. A saved key never changes, because messages already name it.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "value_id",
            "in": "path",
            "required": true,
            "description": "The custom value (GET /v1/custom-values).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters."
                  },
                  "value": {
                    "type": "string",
                    "description": "Up to 5,000 characters."
                  },
                  "folder": {
                    "type": "string",
                    "description": "Up to 60 characters; null takes it out of its folder."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "value": "June 10 at 6 PM"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "custom_value": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "key": "webinar_date",
                      "name": "Webinar date",
                      "value": "June 10 at 6 PM",
                      "folder": "Events",
                      "sort_order": 0,
                      "created_at": "2026-11-14T15:00:00Z",
                      "updated_at": "2026-11-15T09:00:00Z",
                      "token": "{{custom_values.webinar_date}}"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_custom_value",
        "tags": [
          "Pipeline & fields"
        ],
        "summary": "Delete a custom value",
        "description": "Messages that use its token leave that spot empty from then on.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "value_id",
            "in": "path",
            "required": true,
            "description": "The custom value.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "key": "webinar_date"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/review-funnels": {
      "post": {
        "operationId": "create_review_funnel",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Add a review page",
        "description": "A blank page with the usual words, or a copy of another page of the same sub-account (`copy_of`: its look, threshold and settings come along).\n\n- The new page has its own link and stays off until someone turns it on in the app.\n- name, copy and helper follow the rules of `PATCH /v1/review-funnels/{funnel_id}:` words offering something for a review or asking for a particular rating are refused.\n- The sub-account's first page becomes its default.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "copy_of": {
                    "type": "string",
                    "description": "A review page of this sub-account to copy."
                  },
                  "name": {
                    "type": "string",
                    "description": "For the team, up to 60 characters. Default \"New review page\", or \"<name> copy\"."
                  },
                  "copy": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Any of headline (140), message (300), low_title (100), low_message (300), low_button (40), low_thanks (300), high_title (100), high_message (300), high_button (40)."
                  },
                  "helper": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Any of enabled, question (120), chips (up to 8, 32 characters each), keywords (up to 6, 60 characters each), details, ask_photo."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "copy_of": "uuid",
                "name": "Roofing jobs"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "review_funnel": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Roofing jobs",
                      "is_default": false,
                      "enabled": false,
                      "public_code": "ef56gh78",
                      "threshold": 4,
                      "destinations": [],
                      "happy_action": "redirect",
                      "allow_public_when_unhappy": true,
                      "alert_on_unhappy": true,
                      "automation_id": null,
                      "copy": {
                        "headline": "How was your experience with {business}?"
                      },
                      "helper": {
                        "enabled": false,
                        "question": "What did you like most?",
                        "chips": [
                          "On time",
                          "Fair price"
                        ],
                        "keywords": [],
                        "details": true,
                        "ask_photo": false
                      },
                      "created_at": "2026-11-15T15:00:00Z",
                      "updated_at": "2026-11-15T15:00:00Z",
                      "public_path": "/r/ef56gh78"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "list_review_funnels",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Review pages",
        "description": "Tools → Review funnel: each review page, which one is the default, its rating threshold, where happy customers are sent, its words (copy), \"Help them write it\" (helper) and its `public_path` (/r/<code> on the sub-account's domain).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/review-funnels/{funnel_id}": {
      "delete": {
        "operationId": "delete_review_funnel",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Delete a review page",
        "description": "Links already sent for the page open the default page from then on, and its results stay in `GET /v1/review-requests`. Deleting the default page makes the oldest page left the default (`default_funnel_id`; null when none is left).\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "funnel_id",
            "in": "path",
            "required": true,
            "description": "Review page id (GET /v1/review-funnels).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "default_funnel_id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_review_funnel",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Change a review page's words",
        "description": "The team's name for the page, what it says (public, at once) and \"Help them write it\": after a happy rating the customer taps what they liked and the page writes a short review for them to edit and post themselves.\n\n- Send only what changes; copy and helper merge onto what's saved.\n- The star threshold, where unhappy customers go and the thank-you offer can't be changed here, and words offering something for a review or asking for a particular rating are refused (Google's and the FTC's rules).\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "funnel_id",
            "in": "path",
            "required": true,
            "description": "Review page id (GET /v1/review-funnels).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "For the team, up to 60 characters."
                  },
                  "copy": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Any of headline (140), message (300), low_title (100), low_message (300), low_button (40), low_thanks (300), high_title (100), high_message (300), high_button (40). {business} and {first_name} are filled in."
                  },
                  "helper": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Any of enabled, question (120), chips (up to 8, 32 characters each: what customers can tap), keywords (up to 6, 60 characters each: services and towns a review may mention once), details (the optional \"Anything to add?\" box), ask_photo (ask for a photo of the job; it waits for the owner's OK)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "helper": {
                  "enabled": true,
                  "chips": [
                    "On time",
                    "Fair price",
                    "Clean and tidy"
                  ],
                  "ask_photo": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "review_funnel": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Review page",
                      "is_default": true,
                      "enabled": true,
                      "public_code": "ab12cd34",
                      "threshold": 4,
                      "destinations": [],
                      "happy_action": "redirect",
                      "allow_public_when_unhappy": true,
                      "alert_on_unhappy": true,
                      "automation_id": null,
                      "copy": {
                        "headline": "How was your experience with {business}?"
                      },
                      "helper": {
                        "enabled": true,
                        "question": "What did you like most?",
                        "chips": [
                          "On time",
                          "Fair price",
                          "Clean and tidy"
                        ],
                        "keywords": [],
                        "details": true,
                        "ask_photo": true
                      },
                      "created_at": "2026-10-01T15:00:00Z",
                      "updated_at": "2026-11-08T15:00:00Z",
                      "public_path": "/r/ab12cd34"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-widgets": {
      "post": {
        "operationId": "create_website_widget",
        "tags": [
          "Website widget"
        ],
        "summary": "Add a website widget",
        "description": "An AI chat assistant (mode assistant, with a goal) or a booking widget that opens a Smart Form (mode booking, which needs `smart_form_id`).\n\n- It starts as a new one does in the app: named \"Website chat\" or \"Book online\", the goal's quick replies, a chat bubble on the right with a teaser line, turned on.\n- Any field of `PATCH /v1/website-widgets/{widget_id}` can be sent too.\n- The answer carries `install.snippet`, the line to paste on the site; the widget's key is made for you.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "For the team, up to 120 characters."
                  },
                  "mode": {
                    "type": "string",
                    "description": "Default assistant.",
                    "enum": [
                      "assistant",
                      "booking"
                    ]
                  },
                  "goal": {
                    "type": "string",
                    "description": "What the assistant works toward. Default book_appointment.",
                    "enum": [
                      "book_appointment",
                      "customer_support",
                      "lead_capture"
                    ]
                  },
                  "smart_form_id": {
                    "type": "string",
                    "description": "The form a booking widget opens (GET /v1/smart-forms)."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "The calendar it books into; left out is the default one."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "The first message, up to 500 characters."
                  },
                  "quick_replies": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 4 one-tap starters, up to 80 characters each."
                  },
                  "theme": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The look, laid over the starting one: primary_color, position, launcher, teaser_text, title, subtitle and the rest of the widget's theme."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Website chat",
                "goal": "lead_capture",
                "theme": {
                  "primary_color": "#2563eb"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "widget": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Website chat",
                      "mode": "assistant",
                      "goal": "lead_capture",
                      "public_key": "wgt_0123456789abcdef01234567",
                      "enabled": true,
                      "greeting": "Hi there! How can we help today?",
                      "quick_replies": [
                        "Get a quote",
                        "Ask a question",
                        "Have someone call me"
                      ],
                      "theme": {
                        "launcher": "bubble",
                        "position": "right",
                        "teaser_text": "Get a quick quote",
                        "primary_color": "#2563eb"
                      },
                      "allowed_origins": [],
                      "views_count": 0,
                      "conversations_count": 0,
                      "leads_count": 0,
                      "bookings_count": 0,
                      "install": {
                        "origin": "https://crm.youragency.com",
                        "snippet": "<script async src=\"https://crm.youragency.com/widget.js\" data-Local Flywheel-widget=\"wgt_0123456789abcdef01234567\"></script>",
                        "sample_page_url": "https://crm.youragency.com/widget-test.html?key=wgt_0123456789abcdef01234567"
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "list_website_widgets",
        "tags": [
          "Website widget"
        ],
        "summary": "Website widgets",
        "description": "Tools > Website Widget: each chat or booking widget's settings and numbers, and `install.snippet`, the exact line to paste on the business's site, on the sub-account's CRM domain. Make one with `POST /v1/website-widgets` and remove one with `DELETE /v1/website-widgets/{widget_id}`.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "widgets": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Website Widget",
                        "mode": "assistant",
                        "goal": "book_appointment",
                        "public_key": "wgt_0123456789abcdef01234567",
                        "enabled": true,
                        "greeting": "Hi there! How can we help today?",
                        "quick_replies": [
                          "Get a quote"
                        ],
                        "theme": {
                          "primary_color": "#2563eb"
                        },
                        "allowed_origins": [],
                        "views_count": 120,
                        "conversations_count": 14,
                        "leads_count": 6,
                        "bookings_count": 2,
                        "install": {
                          "origin": "https://crm.example.com",
                          "snippet": "<script async src=\"https://crm.example.com/widget.js\" ...></script>",
                          "sample_page_url": "https://crm.example.com/widget-test.html?key=wgt_0123456789abcdef01234567"
                        }
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-widgets/{widget_id}": {
      "delete": {
        "operationId": "delete_website_widget",
        "tags": [
          "Website widget"
        ],
        "summary": "Delete a website widget",
        "description": "It stops showing wherever its line is installed, and its visitor sessions go with it. Leads it brought in and their messages stay.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "widget_id",
            "in": "path",
            "required": true,
            "description": "The widget.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "get_website_widget",
        "tags": [
          "Website widget"
        ],
        "summary": "One website widget",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "widget_id",
            "in": "path",
            "required": true,
            "description": "The widget.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "widget": {
                      "id": "uuid",
                      "name": "Website Widget",
                      "enabled": true,
                      "install": {
                        "origin": "https://crm.example.com",
                        "snippet": "<script async src=\"https://crm.example.com/widget.js\" ...></script>"
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_website_widget",
        "tags": [
          "Website widget"
        ],
        "summary": "Change a website widget",
        "description": "Send what changes; the live widget follows on its next page load. theme merges over the saved look, and null clears one of its fields.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "widget_id",
            "in": "path",
            "required": true,
            "description": "The widget.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Whether it shows on the site."
                  },
                  "mode": {
                    "type": "string",
                    "description": "An AI assistant, or a Smart Form to book (needs smart_form_id).",
                    "enum": [
                      "assistant",
                      "booking"
                    ]
                  },
                  "goal": {
                    "type": "string",
                    "description": "What the assistant works toward.",
                    "enum": [
                      "book_appointment",
                      "customer_support",
                      "lead_capture"
                    ]
                  },
                  "ai_prompt": {
                    "type": "string",
                    "description": "Its own prompt; null uses the sub-account's text message prompt."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "Shown under replies; null uses the texting agent's name."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "The first message, up to 500 characters."
                  },
                  "quick_replies": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 4 one-tap starters, up to 80 characters each."
                  },
                  "collect_contact": {
                    "type": "string",
                    "description": "Ask for details before the first message, or during the chat.",
                    "enum": [
                      "before",
                      "during"
                    ]
                  },
                  "notify_on_handoff": {
                    "type": "boolean",
                    "description": "Tell the team when the assistant can't answer."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "The calendar it books into; null is the default one."
                  },
                  "smart_form_id": {
                    "type": "string",
                    "description": "The form a booking widget opens."
                  },
                  "theme": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The look: primary_color, position (right, left), launcher (bubble, avatar), avatar_url, avatar_video_url, teaser_text, title, subtitle, host_name, host_title, card_headline, card_text, card_bullets, cta_label, secondary_label, secondary_url, phones (show, compact, hide), show_after_seconds (0, 3, 5, 10, 20, 30), hide_on_paths."
                  },
                  "allowed_origins": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only these websites (subdomains included); [] allows any."
                  },
                  "daily_message_cap": {
                    "type": "number",
                    "description": "Messages a day across all visitors, 20-10000."
                  },
                  "session_message_cap": {
                    "type": "number",
                    "description": "Messages a conversation, 5-200."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "greeting": "Hi! Want a quick quote?",
                "theme": {
                  "primary_color": "#2563eb",
                  "phones": "compact"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "widget": {
                      "id": "uuid",
                      "greeting": "Hi! Want a quick quote?"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/settings": {
      "get": {
        "operationId": "get_short_link_settings",
        "tags": [
          "Short links"
        ],
        "summary": "Short Links settings",
        "description": "What the link editor starts from: saved UTM sets, saved pixel ids, the domain new links start on (null is the usual address) and the look new QR codes start from.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "settings": {
                      "workspace_id": "uuid",
                      "default_domain": "go.example.com",
                      "utm_templates": [
                        {
                          "name": "Google profile",
                          "utm_source": "google",
                          "utm_medium": "organic",
                          "utm_campaign": "gbp"
                        }
                      ],
                      "pixels": {
                        "meta": "1234567890123456"
                      },
                      "qr": {
                        "fg": "#0f172a",
                        "bg": "#ffffff",
                        "eye": "",
                        "dots": "rounded",
                        "corners": "rounded",
                        "logo": true,
                        "logoUrl": "",
                        "frame": "none",
                        "frameText": "Scan me",
                        "frameColor": "#0f172a",
                        "transparent": false
                      },
                      "updated_at": "2026-11-12T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_short_link_settings",
        "tags": [
          "Short links"
        ],
        "summary": "Change Short Links settings",
        "description": "Only what's sent changes; each part sent replaces that part. A value that isn't allowed is refused with what is. Links already made keep their own UTM, pixels and QR look.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "default_domain": {
                    "type": "string",
                    "description": "One of the sub-account's short domains (GET /v1/short-links/domains), or null for the usual address."
                  },
                  "utm_templates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 40 saved sets: name (60) and any of utm_source, utm_medium, utm_campaign, utm_term, utm_content (200 each)."
                  },
                  "pixels": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Saved pixel ids: meta (10-20 digits), google (G-XXXXXXX or AW-123456789), tiktok (the pixel id), linkedin (the partner id). null or \"\" removes one."
                  },
                  "qr": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The look new QR codes start from: fg, bg, eye, frameColor (#rrggbb; eye \"\" follows the dots), dots (square, rounded, dots, fluid), corners (square, rounded, circle), logo, logoUrl (https), frame (none, label, bubble, card), frameText (28), transparent. Fields left out go back to the usual look."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "utm_templates": [
                  {
                    "name": "Google profile",
                    "utm_source": "google",
                    "utm_medium": "organic",
                    "utm_campaign": "gbp"
                  }
                ],
                "qr": {
                  "fg": "#1d4ed8",
                  "dots": "dots"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "settings": {
                      "workspace_id": "uuid",
                      "default_domain": null,
                      "utm_templates": [
                        {
                          "name": "Google profile",
                          "utm_source": "google",
                          "utm_medium": "organic",
                          "utm_campaign": "gbp"
                        }
                      ],
                      "pixels": {},
                      "qr": {
                        "fg": "#1d4ed8",
                        "bg": "#ffffff",
                        "eye": "",
                        "dots": "dots",
                        "corners": "rounded",
                        "logo": true,
                        "logoUrl": "",
                        "frame": "none",
                        "frameText": "Scan me",
                        "frameColor": "#0f172a",
                        "transparent": false
                      },
                      "updated_at": "2026-11-15T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/campaigns": {
      "post": {
        "operationId": "create_google_ads_campaign",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Create a Google Ads Search campaign (paused)",
        "description": "A whole Search campaign in one request, checked like the app's New campaign screen: its budget, bidding (Maximize conversions or Maximize conversion value only), locations, languages, up to 20 ad groups each with keywords and 1-3 responsive search ads, plus optional negatives, sitelinks, callouts, snippets and a phone number.\n\n- It is always created PAUSED and spends nothing until `POST /v1/google-ads/changes` turns it on; a status other than PAUSED is refused.\n- `validate_only` has Google check it without creating anything.\n- Field names may be `snake_case` or camelCase.\n- Written to the change history.\n- Owners and admins; the sub-account must have Google Ads connected in the app (409 `not_connected` otherwise).\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "campaign": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "name; daily_budget (the account's currency, 1 or more); bidding { strategy: MAXIMIZE_CONVERSIONS | MAXIMIZE_CONVERSION_VALUE, target_cpa?, target_roas? }; locations [{ id }] (1-100 ids from GET /v1/google-ads/locations); languages? (ids, default 1000 = English); search_partners? (default false); location_mode? (PRESENCE default | PRESENCE_OR_INTEREST); final_url_suffix?; ad_groups [{ name, keywords (1-300: \"roof repair\" phrase, \"[roof repair]\" exact, or { text, match_type }), negatives?, ads [{ headlines (3-15, 30 characters each), descriptions (2-4, 90 each), final_url, path1?, path2? }] }]; negatives?; shared_set_ids?; sitelinks? [{ text, final_url, description1?, description2? }]; callouts?; snippets? [{ header, values }]; phone? { country_code, number }."
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts (GET /v1/google-ads). Default: the one picked in the app."
                  },
                  "validate_only": {
                    "type": "boolean",
                    "description": "Have Google check it and create nothing. Default false."
                  }
                },
                "required": [
                  "workspace_id",
                  "campaign"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "validate_only": true,
                "campaign": {
                  "name": "Roof repair - Austin",
                  "daily_budget": 40,
                  "bidding": {
                    "strategy": "MAXIMIZE_CONVERSIONS"
                  },
                  "locations": [
                    {
                      "id": "1026201"
                    }
                  ],
                  "ad_groups": [
                    {
                      "name": "Roof repair",
                      "keywords": [
                        "roof repair",
                        "[emergency roof repair]"
                      ],
                      "ads": [
                        {
                          "headlines": [
                            "Roof Repair in Austin",
                            "Same-Day Roof Repair",
                            "Free Roof Inspection"
                          ],
                          "descriptions": [
                            "Leaks fixed fast by a local crew.",
                            "Call for a free inspection today."
                          ],
                          "final_url": "https://example.com/roof-repair"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/changes": {
      "post": {
        "operationId": "change_google_ads",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change a Google Ads account",
        "description": "Makes up to 100 changes to a sub-account's Google Ads in one request: all of them or none. They are the same changes the app's Google Ads screens make.\n\n> **Warning:** This can spend real ad money. Turning a campaign, ad group, keyword or ad on, or changing a budget, a bidding strategy or a bid, changes what the account spends. The answer's `can_raise_spend` says whether any change in the request could.\n\nHow to use it:\n- Get the ids (campaign, ad group, keyword, budget, asset) from `GET /v1/google-ads/report`.\n- Send changes: a list of `{ kind, ...fields }`. Every kind and its fields are in the table below. Field names work in `snake_case` or camelCase.\n- Send `validate_only` true first: Google checks the changes and nothing is made.\n- Each applied request is one row of the change history, with a `change_id`. Most can be undone with `POST /v1/google-ads/changes/{change_id}/undo`.\n- A change Google refuses answers 400, and nothing in the request is applied. `details.errors` names the change (`change_index`) and why.\n\nWho can call it: Owners and admins.\n\n### Kinds of change\n\nEach item of changes is `{ kind, ...fields }`. A field ending in ? is optional. status is ENABLED or PAUSED. Any change can also carry label, a name shown in the change history.\n\n| kind | Fields | What it does |\n|---|---|---|\n| `campaign_status` | `campaign_id`, status | Turns a campaign on (ENABLED) or off (PAUSED). |\n| `ad_group_status` | `ad_group_id`, status | Turns an ad group on or off. |\n| `keyword_status` | `ad_group_id`, `criterion_id`, status | Turns a keyword on or off. |\n| `ad_status` | `ad_group_id`, `ad_id`, status | Turns an ad on or off. |\n| `budget_amount` | `budget_id`, amount, previous? | Sets a daily budget in the account's currency. previous (the amount it replaces) makes the change undoable. |\n| `campaign_bidding` | `campaign_id`, strategy, `target_cpa?`, `target_roas?` | strategy is `MAXIMIZE_CONVERSIONS` (optional `target_cpa`) or `MAXIMIZE_CONVERSION_VALUE` (optional `target_roas`). null clears a target. |\n| `campaign_networks` | `campaign_id`, `search_partners`, `display_network` | true or false for each network. |\n| `ad_group_bid` | `ad_group_id`, `cpc_bid` | The ad group's bid, 0.01 to 1000. |\n| `keyword_bid` | `ad_group_id`, `criterion_id`, `cpc_bid` | One keyword's bid, 0.01 to 1000. null goes back to the ad group's bid. |\n| `add_keywords` | `ad_group_id`, keywords | Each keyword is \"roof repair\" (phrase), \"[roof repair]\" (exact) or `{ text, match_type }` with EXACT, PHRASE or BROAD. |\n| `remove_keyword` | `ad_group_id`, `criterion_id` | Removes a keyword. |\n| `add_negatives` | level, `parent_id`, keywords | level is campaign, `ad_group` or `shared_set`; `parent_id` is that campaign, ad group or list. |\n| `remove_negative` | level, `parent_id`, `criterion_id` | Removes one negative keyword. |\n| `create_shared_set` | name, keywords, `campaign_ids` | Makes a shared negative keyword list and attaches it to those campaigns. |\n| `attach_shared_set` | `shared_set_id`, `campaign_id` | Attaches a shared negative list to a campaign. |\n| `detach_shared_set` | `shared_set_id`, `campaign_id` | Detaches it. |\n| `create_rsa` | `ad_group_id`, ad | A responsive search ad: ad is `{ headlines (3-15, 30 characters each), descriptions (2-4, 90 each), final_url, path1?, path2? }`. |\n| `create_ad_group` | `campaign_id`, name, keywords, ads, negatives | A new ad group with its keywords, ads and negatives in one go. Undo removes the ad group. |\n| `campaign_name` | `campaign_id`, name | Renames a campaign. |\n| `campaign_dates` | `campaign_id`, `start_date?`, `end_date?`, `previous_end_date?` | Dates are yyyy-mm-dd. `end_date` null runs it with no end. `previous_end_date` makes an end-date change undoable. |\n| `campaign_geo_mode` | `campaign_id`, mode | PRESENCE (people in the area) or `PRESENCE_OR_INTEREST` (also people interested in it). |\n| `campaign_no_eu_political_ads` | `campaign_id` | Answers Google's \"does this campaign have EU political ads?\" with no. Google wants an answer before location changes. |\n| `add_locations` | `campaign_id`, locations, negative | locations is [`{ id, name? }`] with ids from `GET /v1/google-ads/locations`. negative true excludes them. |\n| `add_proximity` | `campaign_id`, proximity | A radius: { radius, units (MILES or KILOMETERS), address `{ street_address?, city_name?, postal_code?, province_code?, country_code }` }. |\n| `add_languages` | `campaign_id`, `language_ids` | Language ids (1000 is English). |\n| `remove_campaign_criterion` | `campaign_id`, `criterion_id` | Removes a location, radius, language or time slot from a campaign. |\n| `ad_schedule` | `campaign_id`, slots, `remove_criterion_ids` | Replaces the schedule: removes the listed slots, then adds slots [`{ day, start_hour, start_minute, end_hour, end_minute, bid_modifier }`]. day is MONDAY to SUNDAY; minutes are 0, 15, 30 or 45. |\n| `criterion_bid` | `campaign_id`, `criterion_id`, `bid_modifier`, previous? | Bid adjustment of a location, radius or time slot: 0.1 (-90%) to 10 (+900%), null for none. |\n| `device_bid` | `campaign_id`, device, `bid_modifier`, `criterion_id?`, previous? | device is DESKTOP, MOBILE or TABLET. 0 turns the device off (-100%). |\n| `remove_campaign` | `campaign_id` | Removes a campaign. Google can't turn a removed campaign back on. |\n| `remove_ad_group` | `ad_group_id` | Removes an ad group. It can't be turned back on. |\n| `remove_ad` | `ad_group_id`, `ad_id` | Removes an ad. It can't be turned back on. |\n| `add_asset` | `campaign_id`, asset | `campaign_id` null adds it to the whole account. asset is one of `{ type: SITELINK, text, final_url, description1?, description2? }`, `{ type: CALLOUT, text }`, `{ type: STRUCTURED_SNIPPET, header, values }` or `{ type: CALL, country_code, phone_number }`. |\n| `replace_asset` | `campaign_id`, `asset_id`, asset, previous? | Puts a new asset in place of an old one. previous (the old asset) makes it undoable. |\n| `remove_asset` | `campaign_id`, `asset_id`, `field_type` | `field_type` is SITELINK, CALLOUT, `STRUCTURED_SNIPPET` or CALL. |\n| `create_conversion_action` | action | action is `{ name, type (WEBPAGE or UPLOAD_CLICKS), category, counting_type (ONE_PER_CLICK or MANY_PER_CLICK), default_value?, primary? }`. category is one of `SUBMIT_LEAD_FORM`, `BOOK_APPOINTMENT`, `PHONE_CALL_LEAD`, `REQUEST_QUOTE`, CONTACT, `QUALIFIED_LEAD`, `CONVERTED_LEAD`, PURCHASE, SIGNUP, DEFAULT. |\n| `add_ip_blocks` | `campaign_id`, ips | Excludes IP addresses or CIDR ranges. `campaign_id` null uses the account's own list, which covers every campaign type (500 at most). |\n| `remove_ip_block` | `campaign_id`, `criterion_id`, ip? | Removes one IP exclusion. |\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "changes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1-100 changes, each { kind, ... } (snake_case or camelCase fields). E.g. { kind: \"campaign_status\", campaign_id: \"123\", status: \"PAUSED\" } or { kind: \"budget_amount\", budget_id: \"456\", amount: 50, previous: 40 }."
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts. Default: the one picked in the app."
                  },
                  "validate_only": {
                    "type": "boolean",
                    "description": "Check with Google and change nothing. Default false."
                  },
                  "review_id": {
                    "type": "string",
                    "description": "With suggestion_id: marks that suggestion of an AI review as applied once the changes went through."
                  },
                  "suggestion_id": {
                    "type": "string",
                    "description": "The review suggestion these changes come from."
                  }
                },
                "required": [
                  "workspace_id",
                  "changes"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "validate_only": true,
                "changes": [
                  {
                    "kind": "campaign_status",
                    "campaign_id": "21000000001",
                    "status": "PAUSED"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "list_google_ads_changes",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Ads change history",
        "description": "Every change made to the sub-account's Google Ads from the app, the API or Autopilot, newest first: what it was in words (summary), its kind and source, whether it can still be undone (`can_undo`) and when it was.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "Only one Google Ads account's changes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/changes/{change_id}/undo": {
      "post": {
        "operationId": "undo_google_ads_change",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Undo a Google Ads change",
        "description": "Puts back one change from the history that has `can_undo` true, as the app's History > Undo does, and marks it undone.\n\n- Undoing a pause turns the thing back on and undoing a budget cut raises it again, so this can spend real ad money (`can_raise_spend`).\n- 409 when it was already undone or can't be undone from here.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "change_id",
            "in": "path",
            "required": true,
            "description": "A change from GET /v1/google-ads/changes.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "validate_only": {
                    "type": "boolean",
                    "description": "Check with Google and change nothing. Default false."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/recommendations": {
      "get": {
        "operationId": "list_google_ads_recommendations",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google's recommendations",
        "description": "Google's own recommendations for the account, each with its id, type, title, the campaign it is about, what it would change, and whether it can be applied from here (blocked / `needs_input` say why not).\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "One of its Google Ads accounts. Default: the one picked in the app.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/recommendations/apply": {
      "post": {
        "operationId": "apply_google_ads_recommendations",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Apply Google recommendations",
        "description": "Applies up to 100 of Google's recommendations, all or nothing.\n\n> **Warning:** This can spend real ad money: many recommendations raise budgets, add keywords or change bidding.\n\n- Google has no dry run for recommendations, so `validate_only` checks the typed change each one makes instead (checked says which ones that covered).\n- A recommendation Google no longer lists is a 409.\n- Written to the change history.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "recommendation_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ids from GET /v1/google-ads/recommendations (customers/{account}/recommendations/...)."
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts. Default: the one picked in the app."
                  },
                  "validate_only": {
                    "type": "boolean",
                    "description": "Check and change nothing. Default false."
                  }
                },
                "required": [
                  "workspace_id",
                  "recommendation_ids"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/recommendations/dismiss": {
      "post": {
        "operationId": "dismiss_google_ads_recommendations",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Dismiss Google recommendations",
        "description": "Tells Google to stop showing up to 100 recommendations. Nothing in the campaigns changes. Written to the change history.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "recommendation_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ids from GET /v1/google-ads/recommendations."
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts. Default: the one picked in the app."
                  }
                },
                "required": [
                  "workspace_id",
                  "recommendation_ids"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/suggestions": {
      "get": {
        "operationId": "google_ads_suggestions",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Ads suggestions (free)",
        "description": "Rule-based suggestions from the account's own numbers: searches that spent and never converted, keywords and ads that lose money and more. Each comes with the ready-made changes to send to `POST /v1/google-ads/changes`. Free; nothing is changed.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "range",
            "in": "query",
            "required": false,
            "description": "Default last_30d.",
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "last_7d",
                "last_14d",
                "last_30d",
                "last_90d"
              ]
            }
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "One of its Google Ads accounts. Default: the one picked in the app.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/review": {
      "post": {
        "operationId": "start_google_ads_review",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Start an AI review of the Google Ads account",
        "description": "An AI review of the whole account (campaigns, keywords, searches, ads, targeting, Google's recommendations, keyword ideas): a summary and suggestions, each with checked changes ready to apply.\n\n- It costs credits (the answer says how many; returned if the review fails), takes a few minutes and changes nothing by itself.\n- Poll `GET /v1/google-ads/review/{review_id}`.\n- 402 when the credits aren't there.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "range": {
                    "type": "string",
                    "description": "Default last_30d.",
                    "enum": [
                      "today",
                      "last_7d",
                      "last_14d",
                      "last_30d",
                      "last_90d"
                    ]
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts. Default: the one picked in the app."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/review/{review_id}": {
      "get": {
        "operationId": "get_google_ads_review",
        "tags": [
          "Ads & Google"
        ],
        "summary": "One AI review",
        "description": "A review you started (or an Autopilot run): status (processing, completed, failed), the summary, the suggestions with their changes, which were applied or dismissed, and for an Autopilot run what it applied and what Google refused. Reviews are their maker's own, as in the app.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "review_id",
            "in": "path",
            "required": true,
            "description": "From POST /v1/google-ads/review, or last_review_id of GET /v1/google-ads/autopilot.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/autopilot": {
      "get": {
        "operationId": "get_google_ads_autopilot",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Ads Autopilot settings",
        "description": "Autopilot for one Google Ads account: on or off, daily or weekly, its rules, the next and last run with what the last one did, the Google recommendation types it may be allowed to apply, and the credits each run costs. Off until someone turns it on.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "One of its Google Ads accounts. Default: the one picked in the app.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "save_google_ads_autopilot",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Turn Google Ads Autopilot on or off, set its rules",
        "description": "Autopilot is an AI review on a schedule that applies, without asking, the low-risk changes its rules allow and leaves the rest as suggestions.\n\n> **Warning:** Turning it on means real changes to A live ad account and credits for every run, paid by the person who turned it on; with `budget_change_pct` above 0 or budget recommendation types it can raise budgets.\n\n- The first run starts within about 10 minutes.\n- Only what you send changes.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "On or off."
                  },
                  "frequency": {
                    "type": "string",
                    "description": "How often it runs.",
                    "enum": [
                      "daily",
                      "weekly"
                    ]
                  },
                  "rules": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "block_wasted_searches (boolean: exact negatives for searches that spent and never converted), pause_losing_keywords (boolean), pause_losing_ads (boolean), budget_change_pct (0-30: the most a budget moves per run, 0 = never), recommendation_types (list from GET /v1/google-ads/autopilot), max_changes_per_run (1-100)."
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts. Default: the one picked in the app."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "enabled": true,
                "frequency": "weekly",
                "rules": {
                  "block_wasted_searches": true,
                  "pause_losing_keywords": true,
                  "budget_change_pct": 0
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/autopilot/preview": {
      "post": {
        "operationId": "preview_google_ads_autopilot",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Preview an Autopilot run",
        "description": "What an Autopilot run would change right now under the rules sent (or the saved ones), using the free rule-based suggestions: each change is checked with Google, nothing is changed, charged or saved. A real run also has the AI review, so it may find more.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "rules": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Rules to try, as in PUT /v1/google-ads/autopilot. Default: the saved rules."
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts. Default: the one picked in the app."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/autopilot/run": {
      "post": {
        "operationId": "run_google_ads_autopilot",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Run Autopilot now",
        "description": "It answers at once; read the outcome from `GET /v1/google-ads/autopilot` (`last_status`, `last_summary`, `last_review_id`).\n\n> **Warning:** Runs Autopilot right away with its saved settings: This costs credits and makes real changes to the ad account within the saved rules.\n\n409 while a run is under way; 400 until settings were saved.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "One of its Google Ads accounts. Default: the one picked in the app."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/locations": {
      "get": {
        "operationId": "search_google_ads_locations",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Find Google Ads locations",
        "description": "Places by name (cities, regions, ZIP codes, countries) with the ids a campaign's locations and `add_locations` changes take. Up to 15.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "2-80 characters, e.g. Austin.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country_code",
            "in": "query",
            "required": false,
            "description": "Two letters, e.g. US.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/keyword-ideas": {
      "get": {
        "operationId": "google_ads_keyword_ideas",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Keyword ideas",
        "description": "Keyword ideas from Google with monthly searches and top-of-page bids, from seed words, a website, or both. Up to 200.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keywords",
            "in": "query",
            "required": false,
            "description": "Up to 20 seed words, comma-separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "The business's website.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "geo_ids",
            "in": "query",
            "required": false,
            "description": "Up to 10 location ids, comma-separated. Default: campaign_id's locations.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "language_id",
            "in": "query",
            "required": false,
            "description": "Default 1000 (English).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "query",
            "required": false,
            "description": "Use this campaign's locations.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_partners",
            "in": "query",
            "required": false,
            "description": "Include search partners. Default false.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "One of its Google Ads accounts. Default: the one picked in the app.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/social/comment-rules": {
      "get": {
        "operationId": "list_comment_rules",
        "tags": [
          "Messaging"
        ],
        "summary": "List Comment to DM rules",
        "description": "The sub-account's Comment to DM rules (Settings > Instagram & Messenger): when someone comments on the business's Instagram or Facebook post, a rule can reply under the comment and send them a private message.\n\n- Oldest first, which is the order they are tried in: the oldest active rule that matches a comment answers it, so a newer rule with the same keyword never sends.\n- Each has `account_ids` (empty = every connected account), `post_ids` (empty = any post or reel), match (contains: a keyword appears as a whole word; exact: the whole comment is the keyword; any: every comment), keywords, `public_replies` (one is picked at random; empty = no public reply), `dm_text`, button, `once_per_person`, `fired_count` and `last_fired_at`.\n- What each rule did is `GET /v1/social/comments`.\n\nWho can call it: Owners and admins, with Instagram & Messenger on for the account (403 `not_enabled` otherwise).\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "rules": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Free guide",
                        "active": true,
                        "account_ids": [],
                        "post_ids": [],
                        "match": "contains",
                        "keywords": [
                          "guide"
                        ],
                        "public_replies": [
                          "Check your DMs!"
                        ],
                        "dm_text": "Here's the guide you asked for.",
                        "button": {
                          "label": "Get the guide",
                          "url": "https://example.com/guide"
                        },
                        "once_per_person": true,
                        "fired_count": 42,
                        "last_fired_at": "2026-11-14T16:00:00Z",
                        "created_at": "2026-11-01T15:00:00Z",
                        "updated_at": "2026-11-01T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_comment_rule",
        "tags": [
          "Messaging"
        ],
        "summary": "Create a Comment to DM rule",
        "description": "Makes a rule with the editor's own limits. It starts answering new comments as soon as it is saved active (the default): send active false to save it switched off.\n\n- Keywords are cleaned as the editor does (a leading # dropped, no repeats in any case); with match any they are not used.\n- A message with a button can be 640 characters, without one 1,000.\n- `account_ids` must be this sub-account's connected accounts (`GET /v1/social/accounts`).\n\nWho can call it: Owners and admins, with Instagram & Messenger on.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "The rule's name, up to 80 characters."
                  },
                  "dm_text": {
                    "type": "string",
                    "description": "The private message: up to 1,000 characters, 640 with a button."
                  },
                  "match": {
                    "type": "string",
                    "description": "contains (default), exact or any.",
                    "enum": [
                      "contains",
                      "exact",
                      "any"
                    ]
                  },
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 20 keywords of up to 40 characters. Required unless match is any."
                  },
                  "account_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Connected accounts the rule watches. Empty (default) = all of them."
                  },
                  "post_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 100 posts or reels (their ids on Instagram or Facebook). Empty (default) = any post."
                  },
                  "public_replies": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replies under the comment, up to 10 of up to 300 characters; one is picked at random. Empty (default) = none."
                  },
                  "button": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ label (up to 20 characters), url (https) }: a link button under the message. null = none."
                  },
                  "once_per_person": {
                    "type": "boolean",
                    "description": "Send each person this rule's message only once. Default true."
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "required": [
                  "workspace_id",
                  "name",
                  "dm_text"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Free guide",
                "keywords": [
                  "guide"
                ],
                "public_replies": [
                  "Check your DMs!"
                ],
                "dm_text": "Here's the guide you asked for.",
                "button": {
                  "label": "Get the guide",
                  "url": "https://example.com/guide"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/social/comment-rules/{rule_id}": {
      "patch": {
        "operationId": "update_comment_rule",
        "tags": [
          "Messaging"
        ],
        "summary": "Change a Comment to DM rule",
        "description": "Only what is sent changes, and the rule as a whole is checked again (adding a button to a 700-character message is refused). active false switches it off; button null removes the button.\n\nWho can call it: Owners and admins, with Instagram & Messenger on.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "rule_id",
            "in": "path",
            "required": true,
            "description": "The rule (from GET /v1/social/comment-rules).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 80 characters."
                  },
                  "active": {
                    "type": "boolean",
                    "description": "On or off."
                  },
                  "dm_text": {
                    "type": "string",
                    "description": "Up to 1,000 characters, 640 with a button."
                  },
                  "match": {
                    "type": "string",
                    "description": "contains, exact or any.",
                    "enum": [
                      "contains",
                      "exact",
                      "any"
                    ]
                  },
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The whole list, up to 20."
                  },
                  "account_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The whole list. Empty = every connected account."
                  },
                  "post_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The whole list. Empty = any post."
                  },
                  "public_replies": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The whole list, up to 10. Empty = no public reply."
                  },
                  "button": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ label, url } or null."
                  },
                  "once_per_person": {
                    "type": "boolean",
                    "description": "Send each person this rule's message only once."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "active": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_comment_rule",
        "tags": [
          "Messaging"
        ],
        "summary": "Delete a Comment to DM rule",
        "description": "Deletes the rule. Its comment log stays (`GET /v1/social/comments`), without the rule's name.\n\nWho can call it: Owners and admins, with Instagram & Messenger on.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "rule_id",
            "in": "path",
            "required": true,
            "description": "The rule.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/meta-lead-forms": {
      "get": {
        "operationId": "list_meta_lead_pages",
        "tags": [
          "Meta"
        ],
        "summary": "Facebook Pages and Lead Forms that feed Leads",
        "description": "Settings > Leads: the Facebook Pages connected to this sub-account so their Lead Form (Instant Form) leads arrive, and each Page's forms.\n\n- A page's id is the connection (used by the routes below); `page_id` is Facebook's.\n- Each form has connected (only a connected form makes leads), mapped (its questions were matched to lead fields in the app; without that, name, email and phone are recognised by themselves) and, for owners and admins, `held_leads` (leads Meta delivered for a form that isn't connected: they wait until the form is connected and a sync with `include_unconnected` imports them).\n- `import_unconnected_forms` true = leads from forms that aren't connected are imported too.\n- Never a Page token.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "pages": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "page_id": "104857600001",
                        "page_name": "Castillo Roofing",
                        "active": true,
                        "import_unconnected_forms": false,
                        "last_lead_at": "2026-11-14T16:00:00Z",
                        "forms": [
                          {
                            "form_id": "9000000001",
                            "name": "Roof quote",
                            "connected": true,
                            "mapped": true,
                            "held_leads": 0
                          },
                          {
                            "form_id": "9000000002",
                            "name": null,
                            "connected": false,
                            "mapped": false,
                            "held_leads": 3
                          }
                        ],
                        "connected_at": "2026-10-01T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/meta-lead-forms/pages": {
      "post": {
        "operationId": "connect_meta_lead_page",
        "tags": [
          "Meta"
        ],
        "summary": "Connect a Facebook Page's Lead Forms",
        "description": "Connects a Facebook Page to this sub-account so its Lead Form leads arrive, exactly as Connect does in Settings > Leads.\n\n- It needs a Facebook login already connected in the app (the person's own, else the sub-account owner's or the agency's) that fully manages the Page and has approved Lead Ads Retrieval: 409 with `details.code` otherwise (`not_connected`, `missing_leads_retrieval`, `insufficient_page_admin`...) and the words to act on.\n- Connecting a Page does not connect its forms: turn forms on with `PATCH /v1/meta-lead-forms/pages/{id}`.\n- The same Page can feed several sub-accounts.\n- The agency's owner and admins only (the client's admins see the Pages read-only, as in the app).\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "page_id": {
                    "type": "string",
                    "description": "The Facebook Page's id (digits)."
                  }
                },
                "required": [
                  "workspace_id",
                  "page_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "page_id": "104857600001"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/meta-lead-forms/pages/{id}": {
      "patch": {
        "operationId": "update_meta_lead_page",
        "tags": [
          "Meta"
        ],
        "summary": "Connect or disconnect a Page's Lead Forms",
        "description": "Turns forms of a connected Page on or off (the switch on each form in Settings > Leads) and sets `import_unconnected_forms`.\n\n- Only a connected form makes leads; from then on its new leads arrive like any live lead (alerts, the first text and automations, as the sub-account is set up).\n- A form's field mapping, phone number and calendar set in the app are kept; matching a form's questions to lead fields stays in the app, and a form connected here without it still gets name, email and phone recognised.\n- Only forms the Page is known to have (listed by `GET /v1/meta-lead-forms`) can be named.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connected Page's id (from GET /v1/meta-lead-forms; not Facebook's page_id).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "forms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ form_id, connected: true | false, name? }], 1-200. name is kept only for a form that has none yet."
                  },
                  "import_unconnected_forms": {
                    "type": "boolean",
                    "description": "Also make leads from forms that aren't connected."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "forms": [
                  {
                    "form_id": "9000000002",
                    "connected": true
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "disconnect_meta_lead_page",
        "tags": [
          "Meta"
        ],
        "summary": "Disconnect a Facebook Page",
        "description": "Disconnects the Page from this sub-account: its Lead Form leads stop arriving here and its form settings are removed.\n\n- Leads already in the CRM stay.\n- It works even when the Facebook login has expired.\n- `still_connected_elsewhere` true means the same Page still feeds another sub-account.\n- The agency's owner and admins only.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connected Page's id (from GET /v1/meta-lead-forms).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "page_id": "104857600001",
                    "still_connected_elsewhere": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/meta-lead-forms/sync": {
      "post": {
        "operationId": "sync_meta_leads",
        "tags": [
          "Meta"
        ],
        "summary": "Sync past leads from Meta",
        "description": "Sync leads from Meta (Settings > Leads): pulls the last `days` of leads for the connected forms of the connected Pages (`page_ids` / `form_ids` narrow it; up to 2,000 leads a form) and answers 202 with a `sync_id` to follow at `GET /v1/meta-lead-forms/syncs/{sync_id}`.\n\n- A lead that already exists (same Meta lead, phone or email) is updated, never duplicated; a lead deleted in the CRM comes back, because a sync asked for by hand is a re-import.\n- Two switches decide who hears about the NEW leads, both off unless sent (in the app's dialog the first starts on): `notify_team` sends the sub-account's new-lead alerts (emails and texts to its notification recipients) for each one, the same as a live lead; `run_automations` gives each one exactly what a live lead gets: the first text and email (auto-greet), the AI's first message and Instant Lead Connect.\n- Leave `run_automations` off for a backfill so old leads are never texted.\n- Updated leads never alert anyone.\n- `include_unconnected` also imports the leads held for forms that aren't connected.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "days": {
                    "type": "number",
                    "description": "How far back, 1-365. Default 30."
                  },
                  "page_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only these connected Pages (Facebook's page ids). Default: all of them."
                  },
                  "form_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only these forms. Default: every connected form."
                  },
                  "notify_team": {
                    "type": "boolean",
                    "description": "Send the team's new-lead alerts for each new lead. Default false."
                  },
                  "run_automations": {
                    "type": "boolean",
                    "description": "Text and email each new lead like a live one. Default false."
                  },
                  "include_unconnected": {
                    "type": "boolean",
                    "description": "Also import leads held for forms that aren't connected. Default false."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "days": 30
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sync_id": "uuid",
                    "workspace_id": "uuid",
                    "status": "running",
                    "days": 30,
                    "run_automations": false,
                    "notify_team": false,
                    "include_unconnected": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/meta-lead-forms/syncs/{sync_id}": {
      "get": {
        "operationId": "get_meta_lead_sync",
        "tags": [
          "Meta"
        ],
        "summary": "How a Meta lead sync is going",
        "description": "A sync's status (running, completed or failed), `forms_done` of `forms_total`, how many leads were created, updated and skipped, and the same per form with the reason a form couldn't be read. Poll every couple of seconds while it is running.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sync_id",
            "in": "path",
            "required": true,
            "description": "The sync (from POST /v1/meta-lead-forms/sync).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sync_id": "uuid",
                    "workspace_id": "uuid",
                    "status": "completed",
                    "days": 30,
                    "run_automations": false,
                    "page_ids": [
                      "104857600001"
                    ],
                    "form_ids": [],
                    "forms_total": 1,
                    "forms_done": 1,
                    "created": 12,
                    "updated": 3,
                    "skipped": 0,
                    "forms": [
                      {
                        "form_id": "9000000001",
                        "form_name": "Roof quote",
                        "page_id": "104857600001",
                        "created": 12,
                        "updated": 3,
                        "skipped": 0,
                        "error": null
                      }
                    ],
                    "error": null,
                    "started_at": "2026-11-15T15:00:00Z",
                    "finished_at": "2026-11-15T15:00:40Z"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lead-feedback": {
      "get": {
        "operationId": "get_lead_feedback",
        "tags": [
          "Meta"
        ],
        "summary": "Lead quality feedback: the dataset and recent events",
        "description": "Settings > Leads > Lead quality feedback, read only: `dataset_id` (the Meta dataset lead stages are sent back to; null until one is made or picked in the app), enabled (the card's switch; nothing is sent without a dataset), the attached `ad_account_ids`, and `recent_events`: the newest events sent or failed (Lead, QualifiedLead, Schedule, Purchase, DisqualifiedLead) with the lead and Meta's reason for a failure. Making or picking a dataset, the step in Meta's Events Manager and sending test events stay in the app.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many recent events, 1-50. Default 10.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "dataset_id": "1234567890123456",
                    "enabled": true,
                    "ad_account_ids": [
                      "act_123456789"
                    ],
                    "recent_events": [
                      {
                        "id": "uuid",
                        "lead_id": "uuid",
                        "event": "QualifiedLead",
                        "status": "sent",
                        "error": null,
                        "created_at": "2026-11-14T16:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/duplicate": {
      "post": {
        "operationId": "duplicate_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Duplicate a Smart Page",
        "description": "A copy in the same sub-account: the draft, every extra page and file, per-page SEO, the page's settings and its database connection.\n\n- The copy is a draft with a new link and no views, leads, custom domain, builds or waiting prompts.\n- name is optional (default \"<name> copy\"); `include_chat` true also copies the builder chat.\n- Answers copied `{ documents, seo, database, messages }`.\n- Up to 200 pages a sub-account.\n- Copying into another sub-account stays in the app.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The copy's name, up to 80 characters."
                  },
                  "include_chat": {
                    "type": "boolean",
                    "description": "Also copy the builder chat (default false)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Roof repair Fort Worth"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/versions": {
      "get": {
        "operationId": "list_smart_page_versions",
        "tags": [
          "Smart pages"
        ],
        "summary": "List a Smart Page's versions",
        "description": "The page's history, newest first: version (its number), label, `created_at`, by `{ user_id, name }`, document (which document that change was made to, / is the home page), prompt (the request behind a build, shortened), credits and `restore_of` (true when the version is itself a restore). Every build, edit, html write and restore makes one.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many, 1-200 (default 50).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/restore": {
      "post": {
        "operationId": "restore_smart_page_version",
        "tags": [
          "Smart pages"
        ],
        "summary": "Restore a Smart Page version",
        "description": "Puts a version back as the draft, exactly as Restore in the builder: the home page and every extra page that version held; pages made after it are removed, and files that version could not keep (`left_alone`) stay as they are.\n\n- A version from before whole-project history puts back only the one document it kept.\n- The restore is saved as a new version, so restoring the version before it undoes it.\n- 409 while a build is running.\n- Nothing goes live until `POST /v1/smart-pages/{page_id}/publish`.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "number",
                    "description": "The version number from GET /v1/smart-pages/{page_id}/versions."
                  }
                },
                "required": [
                  "version"
                ],
                "additionalProperties": true
              },
              "example": {
                "version": 12
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/seo": {
      "get": {
        "operationId": "get_smart_page_seo",
        "tags": [
          "Smart pages"
        ],
        "summary": "Read a Smart Page's SEO, page by page",
        "description": "`seo.pages`: the home page (/) and each extra page with `seo_title`, `seo_description` and `og_image_url`. An extra page's empty field uses the home page's.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_smart_page_seo",
        "tags": [
          "Smart pages"
        ],
        "summary": "Set the SEO of one page of a Smart Page",
        "description": "Changes only what is sent for the page at path (default /, the home page): `seo_title` (up to 300 characters), `seo_description` (up to 500), `og_image_url` (an https link).\n\n- null clears a field.\n- path must be a page that exists in this Smart Page (404 otherwise).\n- Answers the same view as GET.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "Which page, e.g. /thank-you (default /)."
                  },
                  "seo_title": {
                    "type": "string",
                    "description": "Title for search results and link previews."
                  },
                  "seo_description": {
                    "type": "string",
                    "description": "Description for search results and link previews."
                  },
                  "og_image_url": {
                    "type": "string",
                    "description": "Picture for link previews (https)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "path": "/services/roofing",
                "seo_title": "Roof Replacement in Dallas | Castillo Roofing",
                "seo_description": "Free estimates, 25-year warranty."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/queue/clear": {
      "post": {
        "operationId": "clear_smart_page_queue",
        "tags": [
          "Smart pages"
        ],
        "summary": "Clear a Smart Page's waiting prompts",
        "description": "Drops every prompt waiting in line behind the running build (waiting in `GET /v1/smart-pages/{page_id}/builds`). The build that is running is not touched: `POST /v1/smart-pages/{page_id}/cancel-build` stops it. Answers cleared (how many).\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/queue/pause": {
      "post": {
        "operationId": "pause_smart_page_queue",
        "tags": [
          "Smart pages"
        ],
        "summary": "Pause or resume a Smart Page's build queue",
        "description": "paused true: prompts sent while paused, and the ones already waiting, stay in line.\n\n- paused false: the queue runs again, and when nothing is building the next waiting prompt starts at once (`started_build_id`), costing credits like any build.\n- Answers `queue_paused`, waiting and `started_build_id`.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paused": {
                    "type": "boolean",
                    "description": "true to pause, false to resume."
                  }
                },
                "required": [
                  "paused"
                ],
                "additionalProperties": true
              },
              "example": {
                "paused": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/database": {
      "get": {
        "operationId": "get_smart_page_database",
        "tags": [
          "Smart pages"
        ],
        "summary": "Read a Smart Page's database connection",
        "description": "The business's own database the page reads and writes, when one is connected in the builder: `project_url`, mode (anon: the page talks to it directly; server: through a proxy that holds the secret key), `has_secret_key`, tables [`{ name, columns, allowed }`], `last_verified_at` and `last_error`.\n\n- database is null when none is connected.\n- Its keys are never returned, and connecting or changing it stays in the app.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/domains": {
      "get": {
        "operationId": "list_smart_form_domains",
        "tags": [
          "Smart forms"
        ],
        "summary": "List the sub-account's form and page domains",
        "description": "The sub-account's own domains for Smart Forms and Smart Pages: hostname, verified, `verified_at`, `ownership_status`, `ssl_status`, `last_checked_at` and problem (what the last check found, if anything). Read only: a domain is connected and checked in the app.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `smart_forms:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_smart_form_domain",
        "tags": [
          "Smart forms"
        ],
        "summary": "Add a domain the business owns",
        "description": "Adds a domain for the sub-account's Smart Forms and Smart Pages (and, once verified, its CRM address): a root domain (example.com) or a subdomain (`forms.example.com`), written with or without https://.\n\n- It is saved unverified and the answer carries dns, the record to create at the domain's DNS provider: one CNAME to `portal.usezu.com` for a subdomain; for a root domain the provider's alias-style record (ALIAS / ANAME / CNAME flattening), or A records (their addresses come with a check).\n- Then call `POST /v1/smart-forms/domains/{domain_id}/verify`.\n- A hostname has one owner: 409 `already_added` (with its id) when this sub-account has it, 409 `domain_taken` when another account or the white-label settings hold it.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "hostname": {
                    "type": "string",
                    "description": "The domain, like example.com or forms.example.com."
                  }
                },
                "required": [
                  "workspace_id",
                  "hostname"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "WORKSPACE_ID",
                "hostname": "forms.example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/settings": {
      "get": {
        "operationId": "get_smart_form_settings",
        "tags": [
          "Smart forms"
        ],
        "summary": "Read a smart form's tracking, coupon and booking settings",
        "description": "What `GET /v1/smart-forms/{form_id}` leaves out: tracking (meta pixels with their event, ga4, tiktok, `google_ads`), `thank_you_offer` (the thank-you page's coupon, and shown: whether the page shows it) and booking (`calendar_id`, `scheduling_mode`, lengths, notice, time zone, host, custom hours).\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `smart_forms:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/tracking": {
      "patch": {
        "operationId": "update_smart_form_tracking",
        "tags": [
          "Smart forms"
        ],
        "summary": "Set a smart form's tracking ids",
        "description": "The form's Pixels tab. Only what is sent changes; null clears.\n\n- meta: up to 10 Meta pixels [`{ id (digits), event (fired after a submission; default Lead) }`], replacing the list.\n- ga4: a Google Analytics 4 id (G-XXXXXXXX).\n- tiktok: a TikTok pixel id.\n- `google_ads`: `{ id (AW-...), label }` for the conversion fired after a submission.\n- Each id must be in its platform's own shape (400 otherwise).\n- Answers the settings view.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "meta": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Meta pixels: [{ id, event? }], up to 10. Replaces the list; null or [] removes them."
                  },
                  "ga4": {
                    "type": "string",
                    "description": "Google Analytics 4 id, G-XXXXXXXX."
                  },
                  "tiktok": {
                    "type": "string",
                    "description": "TikTok pixel id."
                  },
                  "google_ads": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ id: \"AW-123456789\", label } or null."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "meta": [
                  {
                    "id": "1234567890123456",
                    "event": "Lead"
                  }
                ],
                "ga4": "G-AB12CD34EF"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/thank-you-offer": {
      "patch": {
        "operationId": "update_smart_form_thank_you_offer",
        "tags": [
          "Smart forms"
        ],
        "summary": "Set the coupon on a smart form's thank-you page",
        "description": "The coupon the thank-you page shows after a booking. Only what is sent changes; null clears a field.\n\n- enabled, headline (up to 80), code (up to 40, saved in capitals), description (up to 300), `cta_label` (up to 40), `cta_url` (a phone number becomes a call link; or an https, tel:, mailto: or sms: link), disclaimer (up to 200).\n- It shows once enabled with a headline or description (shown in the answer).\n- The rest of the thank-you page is `PATCH /v1/smart-forms/{form_id}/screens`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "Show the coupon."
                  },
                  "headline": {
                    "type": "string",
                    "description": "The offer, e.g. $500 OFF."
                  },
                  "code": {
                    "type": "string",
                    "description": "A code the customer can mention."
                  },
                  "description": {
                    "type": "string",
                    "description": "One line on what they get."
                  },
                  "cta_label": {
                    "type": "string",
                    "description": "Button label."
                  },
                  "cta_url": {
                    "type": "string",
                    "description": "Phone number or link for the button."
                  },
                  "disclaimer": {
                    "type": "string",
                    "description": "Small print."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "enabled": true,
                "headline": "$500 OFF",
                "code": "CALLNOW500",
                "description": "Call now and mention this code to lock in $500 off your install.",
                "cta_label": "Call now to claim",
                "cta_url": "(555) 123-4567"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/{form_id}/booking": {
      "patch": {
        "operationId": "update_smart_form_booking",
        "tags": [
          "Smart forms"
        ],
        "summary": "Set how people pick a time on a smart form",
        "description": "The form's own booking settings. Only what is sent changes.\n\n- `scheduling_mode` (exact | `arrival_window`; arrival windows run back to back, so `buffer_minutes` is then 0), `slot_minutes` 5-480, `buffer_minutes` 0-240, `arrival_window_minutes` 30-480, `max_days_ahead` 1-365, `min_notice_hours` 0-720, `slots_per_window` 1-50 (bookings that can share one time), timezone (IANA; null = the sub-account's), `host_user_id` (a member of the sub-account; null = its owner), `use_custom_hours` with `weekly_hours` (`{ mon: [[\"09:00\",\"17:00\"]], ... }`; a day left out is closed; null removes them).\n- A form assigned to a booking calendar follows that calendar's hours, lengths and mode instead.\n- Turning booking on or off and picking the calendar are `PATCH /v1/smart-forms/{form_id}` (`booking_enabled`, `calendar_id`).\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Form id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scheduling_mode": {
                    "type": "string",
                    "description": "exact or arrival_window.",
                    "enum": [
                      "exact",
                      "arrival_window"
                    ]
                  },
                  "slot_minutes": {
                    "type": "number",
                    "description": "Appointment length, 5-480."
                  },
                  "buffer_minutes": {
                    "type": "number",
                    "description": "Gap between appointments, 0-240."
                  },
                  "arrival_window_minutes": {
                    "type": "number",
                    "description": "Arrival window length, 30-480."
                  },
                  "max_days_ahead": {
                    "type": "number",
                    "description": "How far ahead people can book, 1-365 days."
                  },
                  "min_notice_hours": {
                    "type": "number",
                    "description": "Minimum notice, 0-720 hours."
                  },
                  "slots_per_window": {
                    "type": "number",
                    "description": "Bookings per time, 1-50."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA time zone, or null."
                  },
                  "host_user_id": {
                    "type": "string",
                    "description": "The member bookings belong to, or null."
                  },
                  "use_custom_hours": {
                    "type": "boolean",
                    "description": "Use weekly_hours instead of the sub-account's hours."
                  },
                  "weekly_hours": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ mon: [[\"09:00\",\"17:00\"]], ... } or null."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "scheduling_mode": "arrival_window",
                "arrival_window_minutes": 120,
                "max_days_ahead": 30,
                "min_notice_hours": 4
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/pages": {
      "get": {
        "operationId": "list_website_pages",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Every page of the website with its views per device",
        "description": "The pages visitors opened in the last days, most viewed first (up to 200): host, path, title, views, and views on desktop, tablet and mobile.\n\n- pictures lists the devices a page has a picture for in the app's heatmaps.\n- Use a path with `GET /v1/website-analytics/heatmap`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "host",
            "in": "query",
            "required": false,
            "description": "Only this website (a host name like www.example.com), when the code is on several.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "pages": [
                      {
                        "host": "acmeroofing.com",
                        "path": "/",
                        "title": "Acme Roofing",
                        "views": 1800,
                        "desktop": 700,
                        "tablet": 40,
                        "mobile": 1060,
                        "pictures": [
                          "Desktop",
                          "Mobile"
                        ]
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/heatmap": {
      "get": {
        "operationId": "get_website_heatmap",
        "tags": [
          "Website Analytics"
        ],
        "summary": "One page on one device: what people click and how far they scroll",
        "description": "A page's heatmap numbers: views, visitors, `avg_s` (attention time), `exit_rate`, `clicks_total`, elements (the 60 most clicked: its CSS path, label, tag, link, clicks, sessions, rage clicks and dead clicks), reach (percent of views that got to each 5 % of the page, 0 % to 100 %), fold (how much of the page shows without scrolling, percent), `page_height`, attention (average attention in each twentieth of the page, top to bottom) and devices (views per device). The page's picture and every single click's position stay in the app; `has_picture` says whether the app has one.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "The page's path, e.g. /pricing (from GET /v1/website-analytics/pages).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "device",
            "in": "query",
            "required": false,
            "description": "Desktop (default), Mobile or Tablet.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "host",
            "in": "query",
            "required": false,
            "description": "Only this website (host name).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "path": "/pricing",
                    "device": "Mobile",
                    "host": null,
                    "views": 420,
                    "visitors": 380,
                    "avg_s": 38,
                    "exit_rate": 31,
                    "clicks_total": 510,
                    "elements": [
                      {
                        "sel": "main > a.btn",
                        "label": "Get a quote",
                        "tag": "a",
                        "link": null,
                        "href": "/contact",
                        "clicks": 140,
                        "sessions": 131,
                        "rage": 0,
                        "dead": 0
                      }
                    ],
                    "reach": [
                      100,
                      96,
                      90,
                      81,
                      70,
                      61,
                      52,
                      44,
                      37,
                      30,
                      26,
                      22,
                      19,
                      16,
                      13,
                      11,
                      9,
                      8,
                      7,
                      6,
                      5
                    ],
                    "fold": 18,
                    "page_height": 5200,
                    "attention": [
                      14,
                      12,
                      10,
                      8,
                      7,
                      6,
                      5,
                      5,
                      4,
                      4,
                      3,
                      3,
                      3,
                      2,
                      2,
                      2,
                      2,
                      2,
                      2,
                      2
                    ],
                    "devices": {
                      "Mobile": 420,
                      "Desktop": 260
                    },
                    "has_picture": true,
                    "picture_taken_at": "2026-11-12T09:00:00Z"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/recordings": {
      "get": {
        "operationId": "list_website_recordings",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Recorded visits, most worth watching first",
        "description": "The visits that were recorded, as the app's Recordings list: when, entry and exit page, pages, attention time (`engaged_ms`), length of the recording (`duration_ms`), source, channel, ad platform, campaign, place, device, browser, clicks, rage and dead clicks, errors, `quick_backs`, conversions, starred, summary (the AI's one line, when someone asked for it), score (the app's 'worth watching' number: frustration, conversions, time and pages) and the lead it became (`lead_id`, `lead_name`).\n\n- sort best (default) | newest | longest.\n- Filters: frustrated, converted, lead, starred, `from_ads` (true / false), `min_s`, visitor (New | Returning), and the overview's breakdowns (page, source, channel, campaign, ad, referrer, country, region, city, device, browser, os, entry, exit, host).\n- The recording itself plays only in the app; visitor ids are never returned.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "best (default), newest or longest.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-200 (default 50).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "frustrated",
            "in": "query",
            "required": false,
            "description": "Only visits with rage clicks, dead clicks, errors or quick backs.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "converted",
            "in": "query",
            "required": false,
            "description": "Only visits that converted (false: that didn't).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "lead",
            "in": "query",
            "required": false,
            "description": "Only visits that became a lead.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "required": false,
            "description": "Only starred ones.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "min_s",
            "in": "query",
            "required": false,
            "description": "At least this many seconds of attention.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Only visits that opened this page path.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "device",
            "in": "query",
            "required": false,
            "description": "Desktop, Mobile or Tablet.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Only this source (as the overview's dims.source names it).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "total": 37,
                    "limit": 50,
                    "offset": 0,
                    "recordings": [
                      {
                        "id": "uuid",
                        "started_at": "2026-11-12T15:02:00Z",
                        "is_new": true,
                        "host": "acmeroofing.com",
                        "entry_path": "/",
                        "exit_path": "/contact",
                        "pageviews": 4,
                        "engaged_ms": 96000,
                        "duration_ms": 141000,
                        "channel": "Paid social",
                        "source": "Meta Ads",
                        "ad_platform": "Meta Ads",
                        "utm_campaign": "fall-roofs",
                        "country": "US",
                        "region": "TX",
                        "city": "Austin",
                        "device": "Mobile",
                        "browser": "Instagram app",
                        "os": "iOS",
                        "clicks": 9,
                        "rage": 2,
                        "dead": 1,
                        "errors": 0,
                        "quick_backs": 0,
                        "conversions": 1,
                        "starred": false,
                        "summary": null,
                        "score": 21,
                        "lead_id": "uuid",
                        "lead_name": "Dana R."
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/recordings/{recording_id}": {
      "get": {
        "operationId": "get_website_recording",
        "tags": [
          "Website Analytics"
        ],
        "summary": "One recorded visit: its pages and markers",
        "description": "What the app's player shows beside the video: recording (source, campaign and ad ids, referring site, place, device, screen, language, counts, starred, summary, `duration_ms`), lead (the lead this visit became), pages (each page in order with its time, scroll depth and the thank-you page it matched), markers (up to 1,500: clicks with the element's label, rage and dead clicks, form starts, fields touched (names only, never what was typed) and sends, errors, conversions) and `other_visits` (the same visitor's other visits). The video itself and its files are only in the app.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "recording_id",
            "in": "path",
            "required": true,
            "description": "A recorded visit (GET /v1/website-analytics/recordings).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "recording": {
                      "id": "uuid",
                      "started_at": "2026-11-12T15:02:00Z",
                      "last_at": "2026-11-12T15:05:10Z",
                      "is_new": true,
                      "host": "acmeroofing.com",
                      "entry_path": "/",
                      "exit_path": "/contact",
                      "pageviews": 4,
                      "engaged_ms": 96000,
                      "channel": "Paid social",
                      "source": "Meta Ads",
                      "referrer_host": "l.instagram.com",
                      "ad_platform": "Meta Ads",
                      "utm_campaign": "fall-roofs",
                      "country": "US",
                      "city": "Austin",
                      "device": "Mobile",
                      "clicks": 9,
                      "rage": 2,
                      "dead": 1,
                      "errors": 0,
                      "quick_backs": 0,
                      "conversions": 1,
                      "starred": false,
                      "recorded": true,
                      "duration_ms": 141000,
                      "summary": null
                    },
                    "lead": {
                      "id": "uuid",
                      "name": "Dana R."
                    },
                    "pages": [
                      {
                        "at": "2026-11-12T15:02:00Z",
                        "path": "/",
                        "title": "Acme Roofing",
                        "engaged_ms": 31000,
                        "scroll_pct": 64,
                        "device": "Mobile",
                        "goal": null,
                        "quick_back": false
                      }
                    ],
                    "markers": [
                      {
                        "at": "2026-11-12T15:02:40Z",
                        "kind": "click",
                        "path": "/",
                        "label": "Get a quote",
                        "tag": "a",
                        "link": null,
                        "href": "/contact",
                        "rage": false,
                        "dead": false,
                        "form": null,
                        "field": null,
                        "filled": null,
                        "name": null
                      }
                    ],
                    "other_visits": []
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/recordings/{recording_id}/star": {
      "post": {
        "operationId": "star_website_recording",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Star a recording",
        "description": "Marks a recorded visit to keep: starred recordings are kept 180 days instead of 30.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recording_id",
            "in": "path",
            "required": true,
            "description": "A recorded visit.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "uuid",
                    "starred": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "unstar_website_recording",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Take the star off a recording",
        "description": "The recording goes back to the usual 30 days.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recording_id",
            "in": "path",
            "required": true,
            "description": "A recorded visit.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "uuid",
                    "starred": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/forms": {
      "get": {
        "operationId": "list_website_forms",
        "tags": [
          "Website Analytics"
        ],
        "summary": "The website's forms: started, sent, and where people stop",
        "description": "Each form on the website (by page and form name): visits that started it, visits that sent it, and its fields in order with touched, filled and `quit_here` (people whose last field this was before leaving without sending).\n\n- Field names only, never what anyone typed.\n- Takes the overview's filters (device, source, campaign, country, page...).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "device",
            "in": "query",
            "required": false,
            "description": "Desktop, Mobile or Tablet.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Only this source.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Only visits that opened this page path.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "forms": [
                      {
                        "path": "/contact",
                        "form": "quote",
                        "started": 22,
                        "sent": 9,
                        "fields": [
                          {
                            "field": "name",
                            "idx": 0,
                            "touched": 22,
                            "filled": 21,
                            "quit_here": 1
                          },
                          {
                            "field": "phone",
                            "idx": 1,
                            "touched": 20,
                            "filled": 13,
                            "quit_here": 7
                          }
                        ]
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/funnel": {
      "post": {
        "operationId": "get_website_funnel",
        "tags": [
          "Website Analytics"
        ],
        "summary": "How many visits reached each step, in order",
        "description": "A funnel over the last days: 2 to 6 steps, each a page (`{ type: 'page', value: '/pricing', match: 'exact' | 'starts' | 'contains' }`, exact by default) or a conversion (`{ type: 'convert', value: 'Form sent' }`; value '' counts any conversion).\n\n- Answers the visits that reached each step after the one before it.\n- filter narrows the visits like the overview's filters (`{ device: 'Mobile' }`).\n- Only reads: nothing is saved.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "site_id": {
                    "type": "string",
                    "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together."
                  },
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "2-6 steps in order: { type, value, match? }."
                  },
                  "days": {
                    "type": "number",
                    "description": "How many days back, 1-400 (default 30)."
                  },
                  "filter": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Narrow the visits, e.g. { device: 'Mobile', source: 'Meta Ads' }."
                  }
                },
                "required": [
                  "workspace_id",
                  "steps"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "steps": [
                  {
                    "type": "page",
                    "value": "/",
                    "match": "exact"
                  },
                  {
                    "type": "page",
                    "value": "/pricing",
                    "match": "starts"
                  },
                  {
                    "type": "convert",
                    "value": "Form sent"
                  }
                ],
                "days": 30
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "steps": [
                      {
                        "step": {
                          "type": "page",
                          "value": "/",
                          "match": "exact"
                        },
                        "sessions": 1200
                      },
                      {
                        "step": {
                          "type": "page",
                          "value": "/pricing",
                          "match": "starts"
                        },
                        "sessions": 310
                      },
                      {
                        "step": {
                          "type": "convert",
                          "value": "Form sent"
                        },
                        "sessions": 42
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/live": {
      "get": {
        "operationId": "list_website_live",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Who is on the website right now",
        "description": "Visits active in the last 5 minutes (up to 50), newest first: the page they're on, source, country, city, device, pages so far and whether the visit is being recorded.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "visitors": [
                      {
                        "id": "uuid",
                        "last_at": "2026-11-15T16:01:40Z",
                        "started_at": "2026-11-15T15:59:02Z",
                        "path": "/pricing",
                        "source": "Google",
                        "country": "US",
                        "city": "Austin",
                        "device": "Desktop",
                        "pageviews": 3,
                        "recorded": true
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/settings": {
      "get": {
        "operationId": "get_website_settings",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Website Analytics settings",
        "description": "record (visits are recorded), `record_rate` (percent of visits recorded), `mask_text` (every word shown as stars in recordings and heatmaps), hosts (only these websites count; empty = any site the code is on), `blocked_hosts` (websites whose visits are dropped), goals (thank-you pages: a visit that reaches one counts as converted), installed, `last_seen_at`, `last_host` and `recordings_this_month`. The code itself is `GET /v1/website-analytics/install`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "settings": {
                      "record": true,
                      "record_rate": 100,
                      "mask_text": false,
                      "hosts": [],
                      "blocked_hosts": [],
                      "goals": [
                        {
                          "name": "Quote sent",
                          "path": "/thank-you",
                          "match": "exact"
                        }
                      ],
                      "installed": true,
                      "last_seen_at": "2026-11-15T16:01:40Z",
                      "last_host": "acmeroofing.com",
                      "recordings_this_month": 412
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_website_settings",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Change Website Analytics settings",
        "description": "Send only what changes.\n\n- record true / false; `record_rate` 100, 50, 25 or 10; `mask_text`; hosts and `blocked_hosts` (host names like `www.example.com`, up to 50 each; each list is replaced); goals (up to 20 thank-you pages, the whole list is replaced: name up to 60 characters, path starting with /, match exact | starts | contains).\n- Typed text, passwords and card numbers are always hidden in recordings whatever is set here.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "site_id": {
                    "type": "string",
                    "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together."
                  },
                  "record": {
                    "type": "boolean",
                    "description": "Record visits."
                  },
                  "record_rate": {
                    "type": "number",
                    "description": "Percent of visits recorded: 100, 50, 25 or 10."
                  },
                  "mask_text": {
                    "type": "boolean",
                    "description": "Show every word as stars."
                  },
                  "hosts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only these websites count ([] = any)."
                  },
                  "blocked_hosts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Websites whose visits are dropped."
                  },
                  "goals": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Thank-you pages: { name, path, match }. Replaces the list."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "record_rate": 50,
                "goals": [
                  {
                    "name": "Quote sent",
                    "path": "/thank-you",
                    "match": "exact"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "settings": {
                      "record": true,
                      "record_rate": 50,
                      "mask_text": false,
                      "hosts": [],
                      "blocked_hosts": [],
                      "goals": [
                        {
                          "name": "Quote sent",
                          "path": "/thank-you",
                          "match": "exact"
                        }
                      ],
                      "installed": true,
                      "last_seen_at": "2026-11-15T16:01:40Z",
                      "last_host": "acmeroofing.com",
                      "recordings_this_month": 412
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/desk/tasks": {
      "get": {
        "operationId": "list_gbp_desk_tasks",
        "tags": [
          "Ads & Google"
        ],
        "summary": "What waits on a business's Google profile",
        "description": "The Google desk's Tasks for one sub-account: reply (a review reply written and waiting for an OK, or one Google refused), review (a review with no reply written yet), post (a draft waiting for an OK, one that failed, or one approved whose time passed without going out: status stuck with `stuck_reason` `posts_off` | `not_connected` | late), photo (a customer's or crew's photo waiting for an OK, or one Google refused) and fix (a Google connection to connect or reconnect).\n\n- Each task carries its own fields (the review and draft, the post's words, the photo's link, the error).\n- counts adds them up (`older_reviews`: unanswered reviews from before `review_days`, not listed); `by_business` splits them per sub-account.\n- Act on them with the posts, reviews and photos routes.\n\nWho can call it: Owners and admins; needs the Google tools add-on (403 `addon_locked`).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kinds",
            "in": "query",
            "required": false,
            "description": "Only these, comma separated: reply, review, post, photo, fix, google (a detail Google changed by itself: answer it with POST /v1/google-business/desk/google-changes/{change_id}).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "review_days",
            "in": "query",
            "required": false,
            "description": "Reviews from this many days back count, 1-3650 (default 90).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-1500 (default 200); total says how many there are.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "tasks": [
                      {
                        "kind": "reply",
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "workspace_name": "Acme Roofing",
                        "profile_id": "uuid",
                        "at": "2026-11-12T14:00:00Z",
                        "status": "draft",
                        "reviewer_name": "Sam K.",
                        "star_rating": 5,
                        "comment": "Fast and friendly.",
                        "draft_reply": "Thank you, Sam!",
                        "error": null,
                        "source": "google"
                      }
                    ],
                    "total": 1,
                    "counts": {
                      "replies": 1,
                      "reviews": 0,
                      "posts": 0,
                      "photos": 0,
                      "fixes": 0,
                      "older_reviews": 3
                    },
                    "by_business": [
                      {
                        "workspace_id": "uuid",
                        "workspace_name": "Acme Roofing",
                        "replies": 1,
                        "reviews": 0,
                        "posts": 0,
                        "photos": 0,
                        "fixes": 0,
                        "older_reviews": 3
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/desk/feed": {
      "get": {
        "operationId": "list_gbp_desk_feed",
        "tags": [
          "Ads & Google"
        ],
        "summary": "What went out on a business's Google profile",
        "description": "The Google desk's Feed for one sub-account, newest first: post (published posts with their words, button and link on Google), reply (review replies that were sent, with the review), photo and video (uploaded to Google), report (weekly and monthly report emails: subject, how many recipients, `opened_at`), checkin (check-in emails to the owner) and faq (the website FAQ embed: its first questions). Keyset paging: send `next.before` and `next.before_id` back to read on (next is null at the end).\n\nWho can call it: Owners and admins; needs the Google tools add-on.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kinds",
            "in": "query",
            "required": false,
            "description": "Only these, comma separated: post, reply, photo, video, report, checkin, faq.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100 (default 40).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Read on from here: the last answer's next.before.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "before_id",
            "in": "query",
            "required": false,
            "description": "Goes with before: next.before_id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "items": [
                      {
                        "kind": "post",
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "workspace_name": "Acme Roofing",
                        "profile_id": "uuid",
                        "at": "2026-11-12T15:00:00Z",
                        "post_kind": "STANDARD",
                        "title": null,
                        "body": "Storm season is here...",
                        "image_url": null,
                        "cta_type": "CALL",
                        "cta_url": null,
                        "google_post_url": "https://local.google.com/place?id=...",
                        "on_google": true,
                        "source": "ai"
                      }
                    ],
                    "next": {
                      "before": "2026-11-12T15:00:00Z",
                      "before_id": "uuid"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/desk/results": {
      "get": {
        "operationId": "get_gbp_desk_results",
        "tags": [
          "Ads & Google"
        ],
        "summary": "12 weeks of Google profile work and reviews",
        "description": "The Google desk's Results for one sub-account: weeks (the last 12, oldest first: posts, replies, photos, videos and reports that went out, the reviews that came in and their average stars) and businesses (each Google business over the last days: posts, replies, photos, new reviews, their average stars, how many were answered, and when something last went out).\n\nWho can call it: Owners and admins; needs the Google tools add-on.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Each business's last N days, 1-365 (default 30).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "days": 30,
                    "weeks": [
                      {
                        "week": "2026-11-09",
                        "posts": 2,
                        "replies": 3,
                        "photos": 4,
                        "videos": 0,
                        "reports": 1,
                        "reviews": 3,
                        "stars": 4.67
                      }
                    ],
                    "businesses": [
                      {
                        "profile_id": "uuid",
                        "workspace_id": "uuid",
                        "workspace_name": "Acme Roofing",
                        "title": "Acme Roofing",
                        "posts": 8,
                        "replies": 11,
                        "photos": 14,
                        "reviews": 12,
                        "stars": 4.75,
                        "answered": 11,
                        "last_at": "2026-11-14T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/desk/google-changes/{change_id}": {
      "post": {
        "operationId": "answer_gbp_google_change",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Answer something Google changed on a profile",
        "description": "A desk task of kind google is a detail Google (or a customer's suggestion) changed on the profile by itself: its field, Google's version and the business's own.\n\n- choice keep makes Google's version the business's, ours puts the business's version back on Google, dismiss leaves it and stops showing it.\n- keep and ours change the live profile and are recorded as a change that can be undone (`POST /v1/google-business/optimizer/changes/{id}/undo`); the name, address and main category are never sent (they can send a profile back through verification).\n- `dry_run`: true has Google check the change only.\n- status answers kept, reverted, dismissed, gone (Google dropped it meanwhile) or validated.\n\nWho can call it: Owners and admins; needs the Google tools.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "change_id",
            "in": "path",
            "required": true,
            "description": "The task's id (GET /v1/google-business/desk/tasks, kind google).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "choice": {
                    "type": "string",
                    "description": "keep, ours or dismiss."
                  },
                  "dry_run": {
                    "type": "boolean",
                    "description": "true: Google checks it, nothing changes."
                  }
                },
                "required": [
                  "choice"
                ],
                "additionalProperties": true
              },
              "example": {
                "choice": "ours"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "uuid",
                    "field": "hours",
                    "choice": "ours",
                    "status": "reverted"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/photos": {
      "get": {
        "operationId": "list_gbp_photos",
        "tags": [
          "Ads & Google"
        ],
        "summary": "A business's Google photo line",
        "description": "Photos of Google Posts & Photos, in line order (up to 400): status pending (from a customer's review page or the crew's photo link, waiting for an OK), queued (in the line; `scheduled_for` is when it goes to Google), uploading, failed (Google refused it: error says why) or uploaded (on Google: `uploaded_at`, `google_media_url`).\n\n- Also category, position, source (app, link, companycam, review), `added_by`, `keeps_its_spot` (it carries where it was taken, for geotags) and `media_format`.\n- counts: pending, `in_line`, `on_google`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "Only this Google profile (default every profile of the sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "pending, queued, uploading, uploaded or failed.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "photos": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "profile_id": "uuid",
                        "image_url": "https://.../google-photos/.../1.jpg",
                        "category": "AT_WORK",
                        "description": null,
                        "status": "queued",
                        "position": 3,
                        "scheduled_for": "2026-11-18T15:00:00Z",
                        "uploaded_at": null,
                        "on_google": false,
                        "google_media_url": null,
                        "keeps_its_spot": true,
                        "source": "app",
                        "added_by": null,
                        "media_format": "PHOTO",
                        "error": null,
                        "created_at": "2026-11-12T10:00:00Z"
                      }
                    ],
                    "counts": {
                      "pending": 0,
                      "in_line": 1,
                      "on_google": 0
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_gbp_photo",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Add a photo to the Google photo line",
        "description": "A JPG or PNG from a public https link (up to 5 MB, at least 250 x 250 pixels; its type is read from the file itself): copied in and put last in the profile's line, then the line's upload times are worked out again (scheduled says whether that worked).\n\n- It goes to Google on its time by itself only while the profile's automatic uploads are on and Google is connected; photos on Google are public.\n- Needs a Google business on the sub-account (409 `not_connected`) and the Google tools add-on (403 `addon_locked`).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "image_url": {
                    "type": "string",
                    "description": "A public https link to a JPG or PNG."
                  },
                  "category": {
                    "type": "string",
                    "description": "AT_WORK (default), EXTERIOR, INTERIOR, PRODUCT, TEAMS, FOOD_AND_DRINK, ADDITIONAL, COVER or LOGO."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its Google profiles (default its first)."
                  }
                },
                "required": [
                  "workspace_id",
                  "image_url"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "image_url": "https://example.com/jobs/new-roof.jpg",
                "category": "AT_WORK"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "photo": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "image_url": "https://.../google-photos/.../1.jpg",
                      "category": "AT_WORK",
                      "description": null,
                      "status": "queued",
                      "position": 4,
                      "scheduled_for": "2026-11-20T15:00:00Z",
                      "uploaded_at": null,
                      "on_google": false,
                      "google_media_url": null,
                      "keeps_its_spot": false,
                      "source": "app",
                      "added_by": null,
                      "media_format": "PHOTO",
                      "error": null,
                      "created_at": "2026-11-15T16:00:00Z"
                    },
                    "scheduled": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/photos/{photo_id}/approve": {
      "post": {
        "operationId": "approve_gbp_photo",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Add a waiting photo to the line",
        "description": "A pending photo (from a customer or the crew) joins the end of the line, as Add to line in the app; nothing goes to Google before that. 409 when it isn't pending any more. Needs the Google tools add-on.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "photo_id",
            "in": "path",
            "required": true,
            "description": "A pending photo (GET /v1/google-business/photos?status=pending).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "photo": {
                      "id": "uuid",
                      "status": "queued",
                      "position": 5,
                      "scheduled_for": "2026-11-22T15:00:00Z"
                    },
                    "scheduled": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/photos/{photo_id}": {
      "delete": {
        "operationId": "delete_gbp_photo",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Remove a photo from the line or from Google",
        "description": "A pending, queued or failed photo leaves the line (the rest move up). One already on Google is taken off Google too: google says deleted, gone (Google no longer had it), `by_hand` (it was added on Google by hand, so it stays there) or none.\n\n- When Google refuses (409, `details.code` `google_refused`), `here_only`=true removes it here and leaves the one on Google.\n- A photo going up right now answers 409: try again in a minute.\n- Works without the Google tools add-on.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "photo_id",
            "in": "path",
            "required": true,
            "description": "A photo (GET /v1/google-business/photos).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "here_only",
            "in": "query",
            "required": false,
            "description": "true: leave the copy on Google.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "google": "none"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-settings": {
      "get": {
        "operationId": "get_call_settings",
        "tags": [
          "Calls"
        ],
        "summary": "Call recording and voicemail",
        "description": "A sub-account's call recording and voicemail (Settings > Phone): whether calls are recorded (`call_recording_enabled`) and which kinds (`call_recording_inbound`, `call_recording_outbound`, `call_recording_forwarded`; `recording_now` lists the kinds being recorded right now), the announcement callers hear before the call connects, whether voicemail is on and which greeting plays (`voicemail_greeting`: default, typed or recording). notes says so when calls are recorded with no announcement.\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "call_settings": {
                      "workspace_id": "uuid",
                      "call_recording_enabled": true,
                      "call_recording_inbound": true,
                      "call_recording_outbound": true,
                      "call_recording_forwarded": false,
                      "call_recording_announcement": "This call may be recorded for quality and training purposes.",
                      "recording_now": [
                        "inbound",
                        "outbound"
                      ],
                      "voicemail_enabled": true,
                      "voicemail_greeting": "typed",
                      "voicemail_greeting_text": "Hi, you've reached Castillo Roofing. Leave your name and number and we'll call you right back.",
                      "voicemail_greeting_url": null,
                      "notes": []
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_call_settings",
        "tags": [
          "Calls"
        ],
        "summary": "Change call recording and voicemail",
        "description": "Only what's sent changes; what GET answers can be sent straight back. Recording: the switch, the three kinds, and `call_recording_announcement` (spoken to the caller before the call connects; null for none).\n\n- Many states require everyone on a call to agree to being recorded, so keep an announcement while recording is on: the answer's notes says so when there is none (the app recommends it and doesn't refuse either).\n- Voicemail: `voicemail_enabled`, and `voicemail_greeting_text` (3-600 characters), which callers hear in a plain built-in voice and which replaces a recorded greeting; `reset_voicemail_greeting`: true goes back to the standard greeting.\n- A greeting recorded, uploaded or spoken in a chosen voice is made in the app, and so is one number's own greeting (which wins over this one).\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "call_recording_enabled": {
                    "type": "boolean",
                    "description": "Record calls."
                  },
                  "call_recording_inbound": {
                    "type": "boolean",
                    "description": "Calls people make to the business's numbers."
                  },
                  "call_recording_outbound": {
                    "type": "boolean",
                    "description": "Calls placed from the dialer."
                  },
                  "call_recording_forwarded": {
                    "type": "boolean",
                    "description": "Calls forwarded on to another phone."
                  },
                  "call_recording_announcement": {
                    "type": "string",
                    "description": "Spoken before the call connects, up to 500 characters; null for none."
                  },
                  "voicemail_enabled": {
                    "type": "boolean",
                    "description": "Missed callers can leave a message."
                  },
                  "voicemail_greeting_text": {
                    "type": "string",
                    "description": "What callers hear before the beep, 3-600 characters."
                  },
                  "reset_voicemail_greeting": {
                    "type": "boolean",
                    "description": "true: back to the standard greeting."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "call_recording_enabled": true,
                "call_recording_announcement": "This call may be recorded for quality and training purposes."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/notification-settings": {
      "get": {
        "operationId": "get_notification_settings",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "The sub-account's alert and outcome settings",
        "description": "Settings > Notifications' switches for the whole sub-account: `notify_on_appointments` (alerts for new appointments), `notify_on_partials` and `partial_notify_delay_minutes` (alert about a form someone started and never sent, after that wait), `auto_complete_appointments` and `auto_complete_grace_hours` (appointments are marked done that long after they end), `appointment_outcome_digest` (the morning 'mark the outcome' digest).\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "notification_settings": {
                      "workspace_id": "uuid",
                      "notify_on_appointments": true,
                      "notify_on_partials": true,
                      "partial_notify_delay_minutes": 5,
                      "auto_complete_appointments": true,
                      "auto_complete_grace_hours": 24,
                      "appointment_outcome_digest": true
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_notification_settings",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "Change the sub-account's alert and outcome settings",
        "description": "Only what's sent changes; what GET answers can be sent straight back. `partial_notify_delay_minutes` is one of 2, 5, 10, 15 and `auto_complete_grace_hours` one of 2, 12, 24, 48 (the app's own choices).\n\nWho is alerted about new leads is `/v1/alert-recipients`; each person's own alerts are `PUT /v1/notification-settings/mine`.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "notify_on_appointments": {
                    "type": "boolean",
                    "description": "Alerts for new appointments."
                  },
                  "notify_on_partials": {
                    "type": "boolean",
                    "description": "Alerts for forms started and never sent."
                  },
                  "partial_notify_delay_minutes": {
                    "type": "number",
                    "description": "2, 5, 10 or 15."
                  },
                  "auto_complete_appointments": {
                    "type": "boolean",
                    "description": "Mark appointments done by themselves."
                  },
                  "auto_complete_grace_hours": {
                    "type": "number",
                    "description": "2, 12, 24 or 48 hours after they end."
                  },
                  "appointment_outcome_digest": {
                    "type": "boolean",
                    "description": "The morning digest of appointments to mark."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "auto_complete_grace_hours": 48
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/notification-settings/mine": {
      "get": {
        "operationId": "get_my_notification_settings",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "My alerts in a sub-account",
        "description": "The alerts of the person this key belongs to, in this sub-account, never anyone else's: alerts `{ new_lead, lead_reply, incoming_call, appointment_booked, appointment_reminder, missed_call, delivery_failure, team_mention }` (each on until they turn it off) and `tap_opens_lead` (tapping an alert opens the lead).\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "notification_settings": {
                      "workspace_id": "uuid",
                      "alerts": {
                        "new_lead": true,
                        "lead_reply": true,
                        "incoming_call": true,
                        "appointment_booked": true,
                        "appointment_reminder": false,
                        "missed_call": true,
                        "delivery_failure": true,
                        "team_mention": true
                      },
                      "tap_opens_lead": false
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_my_notification_settings",
        "tags": [
          "Routing & alerts"
        ],
        "summary": "Change my alerts in a sub-account",
        "description": "Turns alerts on or off for the person this key belongs to, in this sub-account: only the alerts sent change. It never changes another person's alerts (there is no way to name one).\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "alerts": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The alerts to change: any of new_lead, lead_reply, incoming_call, appointment_booked, appointment_reminder, missed_call, delivery_failure, team_mention, each true or false."
                  },
                  "tap_opens_lead": {
                    "type": "boolean",
                    "description": "Tapping an alert opens the lead."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "alerts": {
                  "appointment_reminder": false
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-senders": {
      "get": {
        "operationId": "list_email_senders",
        "tags": [
          "Setup"
        ],
        "summary": "Email sender identities",
        "description": "The people a sub-account's emails come from (Settings > Email > Sender identities): each has a mailbox name (`local_part`), its address on one of the sub-account's verified sending domains, a From name, whether it is the default, and `signature_html` when it has a signature of its own (null = it uses the sub-account's main signature). domains lists the verified sending domains a sender can be on.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "email_senders": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "local_part": "sarah",
                        "domain_id": "uuid",
                        "address": "sarah@mail.castilloroofing.example.com",
                        "display_name": "Sarah at Castillo Roofing",
                        "is_default": true,
                        "signature_html": null,
                        "created_at": "2026-11-01T15:00:00Z"
                      }
                    ],
                    "domains": [
                      {
                        "id": "uuid",
                        "domain": "mail.castilloroofing.example.com",
                        "is_default": true
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_email_sender",
        "tags": [
          "Setup"
        ],
        "summary": "Add an email sender",
        "description": "A new sender identity, as the app's Add saves it. `local_part` is the mailbox name before the @ (made lowercase, spaces become dots, only letters, digits, dot, dash and underscore kept).\n\n- The address is always on one of the sub-account's verified sending domains: `domain_id` picks one, else the main one; 409 when the sub-account has none yet (verify one in the app, Settings > Email).\n- `display_name` defaults to 'Sarah at <business>'.\n- The first sender becomes the default; `is_default`: true moves the default to this one.\n- `signature_html` is the sender's own signature (`{agent}`, `{business}` and `{city}` are filled in per email): anything in it that runs is taken out when saved (scripts, frames, forms and style blocks, on... handlers, links and pictures that aren't http(s), mailto, tel or an image), up to 50,000 characters.\n- Up to 50 senders; 409 when the address already exists.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "local_part": {
                    "type": "string",
                    "description": "The mailbox name before the @ (sarah)."
                  },
                  "display_name": {
                    "type": "string",
                    "description": "The From name, up to 64 characters."
                  },
                  "domain_id": {
                    "type": "string",
                    "description": "One of the verified sending domains (GET /v1/email-senders domains)."
                  },
                  "signature_html": {
                    "type": "string",
                    "description": "The sender's own signature as HTML; leave out to use the main signature."
                  },
                  "is_default": {
                    "type": "boolean",
                    "description": "Make it the default sender."
                  }
                },
                "required": [
                  "workspace_id",
                  "local_part"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "local_part": "mike",
                "display_name": "Mike at Castillo Roofing"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-senders/{sender_id}": {
      "patch": {
        "operationId": "update_email_sender",
        "tags": [
          "Setup"
        ],
        "summary": "Change an email sender",
        "description": "The mailbox name never changes: delete the sender and add another.\n\nOnly what's sent changes:\n- `display_name`\n- `domain_id` (a verified sending domain of the sub-account)\n- `signature_html` (cleaned as on create; null goes back to the main signature)\n- `is_default`: true (makes it the default; to change the default, make another sender the default)\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sender_id",
            "in": "path",
            "required": true,
            "description": "Sender id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "display_name": {
                    "type": "string",
                    "description": "The From name."
                  },
                  "domain_id": {
                    "type": "string",
                    "description": "A verified sending domain."
                  },
                  "signature_html": {
                    "type": "string",
                    "description": "The sender's own signature as HTML; null to use the main signature."
                  },
                  "is_default": {
                    "type": "boolean",
                    "description": "true makes it the default sender."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "signature_html": "<p><b>{agent}</b><br>{business}</p>"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_email_sender",
        "tags": [
          "Setup"
        ],
        "summary": "Delete an email sender",
        "description": "Removes a sender identity, as the app does: contacts that were set to it go back to the default sender.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sender_id",
            "in": "path",
            "required": true,
            "description": "Sender id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/instant-lead-connect": {
      "get": {
        "operationId": "get_instant_lead_connect",
        "tags": [
          "Calls"
        ],
        "summary": "Instant Lead Connect settings",
        "description": "Instant Lead Connect (Settings > Calls): when a new lead comes in, the business's phone rings its team one after another and whoever answers is connected to the lead.\n\n- The settings as the app shows them; a sub-account that never saved any answers the defaults (off).\n- `call_order` lists who rings: a teammate by `user_id` (never their phone), other phones whole only to people who may change the settings and as their last four digits to everyone else.\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "instant_lead_connect": {
                      "workspace_id": "uuid",
                      "enabled": true,
                      "enabled_sources": [
                        "smart_form",
                        "meta_lead"
                      ],
                      "require_press_1": true,
                      "salesperson_ring_seconds": 25,
                      "lead_ring_seconds": 25,
                      "use_auto_greet": false,
                      "on_greet_failure": "connect",
                      "salesperson_hold_audio": "silence",
                      "salesperson_hold_message": null,
                      "voicemail_behavior": "leave_message",
                      "record_calls": false,
                      "trigger_delay_minutes": 0,
                      "sms_after_no_connect": true,
                      "auto_connect_on_answer": false,
                      "call_order": [
                        {
                          "kind": "member",
                          "user_id": "uuid",
                          "label": "Sam Ortiz",
                          "ring_seconds": null
                        },
                        {
                          "kind": "phone",
                          "phone": "+15551234567",
                          "label": "Front desk",
                          "ring_seconds": 20
                        }
                      ],
                      "assigned_rep_first": true,
                      "quiet_hours_enabled": true,
                      "quiet_hours_start": "18:00",
                      "quiet_hours_end": "08:00",
                      "quiet_hours_timezone": "America/Chicago",
                      "call_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri"
                      ],
                      "skip_busy_reps": true,
                      "retry_ladder": {
                        "enabled": false,
                        "delays_minutes": [
                          5,
                          15,
                          60
                        ]
                      },
                      "whisper_template": null,
                      "whisper_include_form_answers": false,
                      "call_on_booking": true,
                      "booking_whisper_template": null,
                      "transcribe_recordings": false
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_instant_lead_connect",
        "tags": [
          "Calls"
        ],
        "summary": "Change Instant Lead Connect",
        "description": "Only what's sent changes, by the app's own limits.\n\n- enabled: true makes the business's phone call its team for every new lead from the sources ticked, from then on (409 while the sub-account has no phone number); this route itself never starts a call.\n- `call_order` replaces the list: `{ kind: \"member\", user_id }` rings a teammate on the phone saved on their own profile (400 when they aren't on the team or have no phone there; a phone can't be typed for a teammate), `{ kind: \"phone\", phone, label }` rings any other number; each may carry `ring_seconds` 10-60; up to 20.\n- Ring times 10-60 seconds, `trigger_delay_minutes` 0-120, quiet hours as 24-hour times with a time zone and `call_days` (at least one), `retry_ladder` up to 6 waits of 1-720 minutes, whisper templates up to 1,000 characters.\n- Auto greets (the recorded greeting a lead hears) are made in the app.\n- Only the sub-account's owner and the owner's own team (the agency side) may change it, as in the app.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Call the team for new leads."
                  },
                  "enabled_sources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Which leads: smart_form, meta_lead, api, webhook, website, manual."
                  },
                  "call_order": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Who rings, in order: [{ kind: \"member\", user_id, ring_seconds? } | { kind: \"phone\", phone, label?, ring_seconds? }]."
                  },
                  "assigned_rep_first": {
                    "type": "boolean",
                    "description": "Ring the lead's assigned person first."
                  },
                  "skip_busy_reps": {
                    "type": "boolean",
                    "description": "Skip someone already on a call."
                  },
                  "salesperson_ring_seconds": {
                    "type": "number",
                    "description": "10-60."
                  },
                  "lead_ring_seconds": {
                    "type": "number",
                    "description": "10-60."
                  },
                  "trigger_delay_minutes": {
                    "type": "number",
                    "description": "Wait before calling, 0-120."
                  },
                  "require_press_1": {
                    "type": "boolean",
                    "description": "The teammate presses 1 to take the call."
                  },
                  "auto_connect_on_answer": {
                    "type": "boolean",
                    "description": "Connect as soon as the teammate answers."
                  },
                  "record_calls": {
                    "type": "boolean",
                    "description": "Record these calls."
                  },
                  "transcribe_recordings": {
                    "type": "boolean",
                    "description": "Write out the recordings."
                  },
                  "sms_after_no_connect": {
                    "type": "boolean",
                    "description": "Text the lead when nobody could be connected."
                  },
                  "quiet_hours_enabled": {
                    "type": "boolean",
                    "description": "Hold calls outside the hours below."
                  },
                  "quiet_hours_start": {
                    "type": "string",
                    "description": "When quiet hours start, like 18:00."
                  },
                  "quiet_hours_end": {
                    "type": "string",
                    "description": "When they end, like 08:00."
                  },
                  "quiet_hours_timezone": {
                    "type": "string",
                    "description": "IANA time zone."
                  },
                  "call_days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Days calls may go out while quiet hours are on: sun..sat."
                  },
                  "retry_ladder": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ enabled, delays_minutes: [5, 15, 60] }."
                  },
                  "whisper_template": {
                    "type": "string",
                    "description": "What the teammate hears first; {{first_name}}, {{full_name}}, {{business_name}}, {{lead_source}}, {{service}}..."
                  },
                  "whisper_include_form_answers": {
                    "type": "boolean",
                    "description": "Read the lead's form answers out too."
                  },
                  "call_on_booking": {
                    "type": "boolean",
                    "description": "Also call when a lead books."
                  },
                  "booking_whisper_template": {
                    "type": "string",
                    "description": "The whisper for a booking; {{appointment_time}} too."
                  },
                  "use_auto_greet": {
                    "type": "boolean",
                    "description": "Play the lead a greeting first."
                  },
                  "on_greet_failure": {
                    "type": "string",
                    "description": "connect, end or backup.",
                    "enum": [
                      "connect",
                      "end",
                      "backup"
                    ]
                  },
                  "salesperson_hold_audio": {
                    "type": "string",
                    "description": "What the teammate hears while the lead is rung.",
                    "enum": [
                      "silence",
                      "tone",
                      "message",
                      "music"
                    ]
                  },
                  "salesperson_hold_message": {
                    "type": "string",
                    "description": "The short message, when hold audio is message."
                  },
                  "voicemail_behavior": {
                    "type": "string",
                    "description": "When the lead's voicemail answers.",
                    "enum": [
                      "leave_message",
                      "drop"
                    ]
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "quiet_hours_enabled": true,
                "quiet_hours_start": "18:00",
                "quiet_hours_end": "08:00",
                "call_days": [
                  "mon",
                  "tue",
                  "wed",
                  "thu",
                  "fri"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/instant-lead-connect/history": {
      "get": {
        "operationId": "list_instant_lead_connect_history",
        "tags": [
          "Calls"
        ],
        "summary": "Instant Lead Connect calls",
        "description": "Its calls, newest first: the lead (`lead_id`, `lead_name`), where the lead came from, who was rung (`recipient_label`, never their phone), `connection_status` and `final_outcome`, whether each side answered and how long each rang, how long they talked, whether there is a recording (`has_recording`; the recording itself is played in the app), the transcript when there is one, and `retry_attempt`.\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100 (default 25).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "Only this lead's calls.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "calls": [
                      {
                        "id": "uuid",
                        "lead_id": "uuid",
                        "lead_name": "Pat Morgan",
                        "source": "smart_form",
                        "recipient_label": "Sam Ortiz",
                        "connection_status": "connected",
                        "final_outcome": "connected",
                        "salesperson_answered": true,
                        "salesperson_ring_duration_seconds": 6,
                        "lead_answered": true,
                        "lead_ring_duration_seconds": 9,
                        "bridge_duration_seconds": 184,
                        "has_recording": true,
                        "transcription": null,
                        "transcription_status": null,
                        "retry_attempt": 0,
                        "created_at": "2026-11-14T15:02:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/phone-numbers/{phone_number_id}": {
      "patch": {
        "operationId": "update_phone_number",
        "tags": [
          "Setup"
        ],
        "summary": "Change a phone number's settings",
        "description": "Settings > Phone > Edit on a number, and who uses it (Team). Only what's sent changes.\n\n- `friendly_name`.\n- Call forwarding: `forward_to` (a phone number, or null to clear it), `forward_enabled` (400 with nothing to forward to), `forward_caller_id` (line: the forwarded phone sees the business's number; caller: the caller's own).\n\nring_order:\n- who the number rings one after another instead of everyone at once, { on, screen, steps: [{ seconds: 10-60, targets: [`{ kind: \"member\", user_id, app, phone }` | `{ kind: \"phone\", phone, label }`] }] }: up to 8 steps of up to 5 people and 180 seconds in all\n- screen makes a phone that answers press 1 to take the call\n- null clears it\n- refused when a step names someone off the team or one of the business's own numbers\n\n- `assigned_user_id` gives the number to one teammate (it rings only them; null shares it with everyone; 400 for someone off the team), `tech_can_answer` and `tech_can_use` say whether it rings technicians and whether they may call and text from it.\n- Forwarding and the ring order change where real calls go from the next call on.\n- The answer is the number as `GET /v1/phone-numbers` lists it plus `voice_forward_caller_id` and `has_forward_to`: the forwarding number and the ring order's phones are never returned.\n- Buying and releasing numbers, and a number's own voicemail greeting, stay in the app.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `phone_numbers:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "phone_number_id",
            "in": "path",
            "required": true,
            "description": "The number's id (GET /v1/phone-numbers).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "friendly_name": {
                    "type": "string",
                    "description": "The number's name, up to 64 characters."
                  },
                  "forward_to": {
                    "type": "string",
                    "description": "The phone calls forward to; null clears it."
                  },
                  "forward_enabled": {
                    "type": "boolean",
                    "description": "Forward calls nobody answers in the app."
                  },
                  "forward_caller_id": {
                    "type": "string",
                    "description": "What the forwarded phone sees.",
                    "enum": [
                      "line",
                      "caller"
                    ]
                  },
                  "ring_order": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ on, screen, steps: [{ seconds, targets }] }; null clears it."
                  },
                  "assigned_user_id": {
                    "type": "string",
                    "description": "The teammate the number belongs to; null for everyone."
                  },
                  "tech_can_answer": {
                    "type": "boolean",
                    "description": "It rings technicians."
                  },
                  "tech_can_use": {
                    "type": "boolean",
                    "description": "Technicians may call and text from it."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "friendly_name": "Main line",
                "assigned_user_id": null
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/profiles/{profile_id}/automation": {
      "patch": {
        "operationId": "update_gbp_profile_automation",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Automatic Google replies, posts and photos",
        "description": "The switches of Google Review Replies and Posts & Photos on one Google profile.\n\n- Only what's sent changes.\n- Turning these on makes things go to the business's public Google profile later, by themselves, with nobody approving each one: `replies_enabled` answers new reviews (a review with at least `replies_auto_min_stars` stars, 1-5, is answered on Google without asking; 6 makes every reply wait for approval); `posts_enabled` writes posts ahead (`posts_per_week` 1-7 at `posts_hour` 0-23 on the business's clock) and, with `posts_auto_publish` true, publishes them on Google by themselves (otherwise each waits for approval); `photos_enabled` adds `photos_per_week` (1-14) photos from the photo line at `photos_hour`.\n- Also `replies_tone` (warm, professional, casual, upbeat) and `posts_use_photos`.\n- The answer's `goes_out_by_itself` lists, in plain words, what now reaches Google without an approval.\n- Turning a switch off is always safe.\n\nWho can call it: Owners and admins of the sub-account, with the Google tools add-on (403 `addon_locked` without it).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "path",
            "required": true,
            "description": "Google profile id (GET /v1/google-business/profiles).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "replies_enabled": {
                    "type": "boolean",
                    "description": "Answer new reviews automatically."
                  },
                  "replies_auto_min_stars": {
                    "type": "number",
                    "description": "1-5: reviews with at least this many stars are answered without asking; 6: always ask first."
                  },
                  "replies_tone": {
                    "type": "string",
                    "description": "The replies' tone.",
                    "enum": [
                      "warm",
                      "professional",
                      "casual",
                      "upbeat"
                    ]
                  },
                  "posts_enabled": {
                    "type": "boolean",
                    "description": "Write Google posts ahead."
                  },
                  "posts_auto_publish": {
                    "type": "boolean",
                    "description": "Publish them without an approval."
                  },
                  "posts_per_week": {
                    "type": "number",
                    "description": "1-7."
                  },
                  "posts_hour": {
                    "type": "number",
                    "description": "0-23, the business's clock."
                  },
                  "posts_use_photos": {
                    "type": "boolean",
                    "description": "Use the business's photos on posts."
                  },
                  "photos_enabled": {
                    "type": "boolean",
                    "description": "Add photos from the photo line to Google."
                  },
                  "photos_per_week": {
                    "type": "number",
                    "description": "1-14."
                  },
                  "photos_hour": {
                    "type": "number",
                    "description": "0-23."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "replies_auto_min_stars": 6
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "replies_enabled": true,
                      "replies_auto_min_stars": 6,
                      "replies_tone": "warm",
                      "posts_enabled": false,
                      "posts_auto_publish": false,
                      "posts_per_week": 2,
                      "posts_hour": 10,
                      "posts_use_photos": true,
                      "photos_enabled": false,
                      "photos_per_week": 2,
                      "photos_hour": 11,
                      "updated_at": "2026-11-15T16:00:00Z",
                      "goes_out_by_itself": [
                        "Replies to new reviews are written and wait for approval."
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/media/{media_id}": {
      "delete": {
        "operationId": "delete_media",
        "tags": [
          "Media"
        ],
        "summary": "Delete a media file",
        "description": "Deletes a file from the sub-account's Media page, as the page's delete does: the row, and its file only when it was uploaded into Media itself (`files_removed`; a tool result saved into Media points at the original ad's file, which stays).\n\n- It cannot be undone.\n- Owners and agency admins delete any file; a client admin only files they added themselves (403); other roles can't; a file that isn't shared with the client's team is a 404 to them.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "media_id",
            "in": "path",
            "required": true,
            "description": "File id (GET /v1/media).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "files_removed": 1
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_media",
        "tags": [
          "Media"
        ],
        "summary": "Rename, move, share or hide a file",
        "description": "Send what changes. Owners and agency admins change any file; client admins only files they added, and those stay shared.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "media_id",
            "in": "path",
            "required": true,
            "description": "The file.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters."
                  },
                  "folder_id": {
                    "type": "string",
                    "description": "A folder of this sub-account, or null for no folder."
                  },
                  "visible_to_client": {
                    "type": "boolean",
                    "description": "Share with or hide from the client's team."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "folder_id": "uuid",
                "visible_to_client": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "media": {
                      "id": "uuid",
                      "folder_id": "uuid",
                      "visible_to_client": true
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/my-booking-link": {
      "get": {
        "operationId": "get_my_booking_link",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "My booking link",
        "description": "The personal booking page of the person this key belongs to, in this sub-account (Calendars > My booking link): its url and settings, or `booking_link`: null when they have none. Never anyone else's.\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `bookings:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "booking_link": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "slug": "sam-ortiz-k3x9",
                      "title": "Book a call",
                      "description": null,
                      "duration_minutes": 30,
                      "buffer_minutes": 0,
                      "min_notice_minutes": 60,
                      "max_days_ahead": 14,
                      "meeting_type": "zoom",
                      "meeting_location": null,
                      "require_email": true,
                      "require_phone": false,
                      "confirm_button_text": null,
                      "is_active": true,
                      "timezone": null,
                      "url": "https://crm.example.com/b/sam-ortiz-k3x9",
                      "created_at": "2026-11-01T15:00:00Z",
                      "updated_at": "2026-11-01T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_my_booking_link",
        "tags": [
          "Calendars & hours"
        ],
        "summary": "Make or change my booking link",
        "description": "For the person this key belongs to, in this sub-account.\n\n- With none yet it makes one as the app's Create does (a 30-minute 'Book a call', its link name from their name plus four random characters) with anything sent laid over it (201); otherwise only what's sent changes.\n- slug is the end of the link (lowercase letters, numbers and dashes, up to 40) and one namespace for everyone: 409 when taken.\n- title up to 60, `duration_minutes` 5-240, `buffer_minutes` 0-120, `max_days_ahead` 1-60, `meeting_type` zoom, `google_meet`, phone, `in_person` or custom (`meeting_location` is the address or link), `confirm_button_text` up to 40, `is_active`: false pauses the page.\n- Their hours and connected calendars are set in the app.\n\nWho can call it: Anyone in the sub-account.\n\nRequired scope: `bookings:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "slug": {
                    "type": "string",
                    "description": "The end of the link."
                  },
                  "title": {
                    "type": "string",
                    "description": "The page's title."
                  },
                  "description": {
                    "type": "string",
                    "description": "A few words under it."
                  },
                  "duration_minutes": {
                    "type": "number",
                    "description": "5-240."
                  },
                  "buffer_minutes": {
                    "type": "number",
                    "description": "0-120."
                  },
                  "min_notice_minutes": {
                    "type": "number",
                    "description": "How soon someone can book."
                  },
                  "max_days_ahead": {
                    "type": "number",
                    "description": "1-60."
                  },
                  "meeting_type": {
                    "type": "string",
                    "description": "Where it happens.",
                    "enum": [
                      "zoom",
                      "google_meet",
                      "phone",
                      "in_person",
                      "custom"
                    ]
                  },
                  "meeting_location": {
                    "type": "string",
                    "description": "The address, or the meeting link or note."
                  },
                  "require_email": {
                    "type": "boolean",
                    "description": "Ask for an email."
                  },
                  "require_phone": {
                    "type": "boolean",
                    "description": "Ask for a phone number."
                  },
                  "confirm_button_text": {
                    "type": "string",
                    "description": "The button's words, up to 40 characters."
                  },
                  "is_active": {
                    "type": "boolean",
                    "description": "false pauses the page."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "title": "Roof inspection call",
                "duration_minutes": 20
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/import": {
      "post": {
        "operationId": "import_leads",
        "tags": [
          "CRM leads"
        ],
        "summary": "Import leads quietly (up to 500 a call)",
        "description": "Adds a list of leads the way the Leads page's Import does: nothing is sent and nothing starts.\n\n- No first text, no new-lead or tag automations, no AI calls, no team alerts, no `lead.created` webhook, no push to job software; \"Leads imported\" automations are not started from the API either.\n- Each lead takes the fields of `POST /v1/leads` (`full_name`, email, phone, `extra_phones`, notes, address, city, state, zip, `custom_fields`, tags, status, `stage_key`, `assigned_to`, `existing_customer`, deal fields...) except source (always import) and `run_intake`; a lead needs a name, an email or a phone.\n- tags go on every lead on top of its own (new tags are made; names are cut at 40 characters).\n- `existing_customers` true adds them as existing customers: won with no sale date, out of the pipeline and every lead count.\n- A lead imported as won gets no sale date unless `deal_won_at` is sent.\n- Duplicates: a row whose email or phone (last 10 digits, main number or one of a lead's other numbers) is already in the sub-account, or earlier in the same call, is skipped and listed with the lead it matched; `on_duplicate` create imports it anyway where the sub-account allows a second record.\n- Rows that can't be used are listed in refused with their index and why; the rest still go in.\n- Send more than 500 in several calls.\n- 201 when at least one lead went in, else 200.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "leads": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1-500 leads, each an object with the fields of POST /v1/leads."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tag names for every lead in this call."
                  },
                  "existing_customers": {
                    "type": "boolean",
                    "description": "Add them as existing customers, not leads (a lead's own existing_customer wins). Default false."
                  },
                  "on_duplicate": {
                    "type": "string",
                    "description": "skip (default) or create.",
                    "enum": [
                      "skip",
                      "create"
                    ]
                  },
                  "file_name": {
                    "type": "string",
                    "description": "Where the list came from (kept on each lead), up to 200 characters."
                  }
                },
                "required": [
                  "workspace_id",
                  "leads"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "tags": [
                  "Spring list"
                ],
                "leads": [
                  {
                    "full_name": "Jane Doe",
                    "email": "jane@example.com",
                    "phone": "+14155550123",
                    "city": "Tampa",
                    "tags": [
                      "VIP"
                    ]
                  },
                  {
                    "full_name": "Sam Roe",
                    "phone": "(415) 555-0142"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "imported": 1,
                    "duplicates_skipped": 1,
                    "refused_count": 0,
                    "leads": [
                      {
                        "index": 0,
                        "id": "uuid"
                      }
                    ],
                    "duplicates": [
                      {
                        "index": 1,
                        "matched_on": "phone",
                        "lead_id": "uuid",
                        "of_index": null
                      }
                    ],
                    "refused": [],
                    "note": "Imported quietly: no texts, emails, calls, alerts or automations were started for these leads."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/bulk": {
      "post": {
        "operationId": "bulk_update_leads",
        "tags": [
          "CRM leads"
        ],
        "summary": "One change on many leads (up to 500)",
        "description": "The Leads page's bulk bar: one action on every lead in `lead_ids`.\n\n- `add_tags` / `remove_tags` (tags by name; new ones are made; a lead holds 50 at most), `set_stage` (`stage_key` from `GET /v1/stages`; a lead that becomes won gets today's sale date unless it has one), assign (`assigned_to`: a member's user id from `GET /v1/members`, or null to unassign; goes on each lead's timeline; the agency owner can't be picked by someone else), `set_existing_customer` (`existing_customer` true | false; only the flag, the stage stays).\n- Each lead is written exactly like `PATCH /v1/leads/{lead_id}` with that one field, so automations and webhooks that start on a tag, a stage or a status change run for each lead as usual.\n- Every id must be a lead of this sub-account: any other id is refused as \"Lead not found\" and never touched.\n- The answer says how many changed and lists the refused ids with why.\n- No messages are sent by this route.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "lead_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1-500 lead ids."
                  },
                  "action": {
                    "type": "string",
                    "description": "What to do to each of them.",
                    "enum": [
                      "add_tags",
                      "remove_tags",
                      "set_stage",
                      "assign",
                      "set_existing_customer"
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "add_tags, remove_tags: tag names."
                  },
                  "stage_key": {
                    "type": "string",
                    "description": "set_stage: the stage's key."
                  },
                  "assigned_to": {
                    "type": "string",
                    "description": "assign: a member's user id, or null to unassign."
                  },
                  "existing_customer": {
                    "type": "boolean",
                    "description": "set_existing_customer: true or false."
                  }
                },
                "required": [
                  "workspace_id",
                  "lead_ids",
                  "action"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_ids": [
                  "uuid",
                  "uuid"
                ],
                "action": "add_tags",
                "tags": [
                  "Spring promo"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "action": "add_tags",
                    "changed": 2,
                    "refused_count": 0,
                    "refused": []
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/bulk-delete": {
      "post": {
        "operationId": "bulk_delete_leads",
        "tags": [
          "CRM leads"
        ],
        "summary": "Delete many leads for good (up to 500)",
        "description": "Deletes every lead in `lead_ids`, each the way `DELETE /v1/leads/{lead_id}` does.\n\n- It can't be undone, so confirm: true is required.\n- With `delete_appointments` true each lead's appointments are deleted first the way the calendar deletes one (the synced calendar event, the customer's cancellation notice, the reminders); without it they stay on the calendar with no lead.\n- Every id must be a lead of this sub-account: any other id is refused as \"Lead not found\".\n- The answer says how many were deleted and lists the refused ids.\n- Needs an admin key, like deleting one lead.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `leads:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "lead_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1-500 lead ids."
                  },
                  "confirm": {
                    "type": "boolean",
                    "description": "Must be true."
                  },
                  "delete_appointments": {
                    "type": "boolean",
                    "description": "Also delete the leads' appointments (tells each customer theirs is cancelled). Default false."
                  }
                },
                "required": [
                  "workspace_id",
                  "lead_ids",
                  "confirm"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_ids": [
                  "uuid",
                  "uuid"
                ],
                "confirm": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": 2,
                    "refused_count": 0,
                    "refused": []
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-campaigns": {
      "post": {
        "operationId": "create_call_campaign",
        "tags": [
          "Calls"
        ],
        "summary": "Create an AI calling campaign (always a draft)",
        "description": "Saves a new outbound AI calling campaign as a draft: nobody is enrolled and nothing is dialled.\n\n- Starting or resuming a campaign places real, paid calls, so that is done in the app (Campaigns).\n- Who it calls: `audience_statuses` (built-in stages: new, contacted, qualified, booked, partial; default new, contacted, partial), `audience_stages` (custom stage keys), `audience_sources`, `audience_tag_ids`, `audience_created_within_days`, `audience_skip_booked` (default true: leads with an appointment on the calendar are skipped); won, lost and spam leads, leads with no phone or a bad number, and leads who asked not to be called are never called.\n- What the agent says: `agent_name`, goal, offer, greeting, script, `extra_instructions`, `transfer_number`, `calendar_id`; a field left out uses the sub-account's AI caller settings.\n- When: `call_days` and `call_window_start` / `call_window_end` in the sub-account's time zone, `run_days`, `start_at`, `max_attempts_per_lead`, `hours_between_attempts`, `daily_call_cap`, `max_concurrent_calls`, `stop_on_reply`, `spend_cap_credits`.\n- The calendar, tags and stages named must be the sub-account's own.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "The campaign's name, up to 120 characters."
                  },
                  "audience_statuses": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Built-in stages to call: new, contacted, qualified, booked, partial. Empty with no audience_stages = every open lead."
                  },
                  "audience_stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Custom stage keys to call (GET /v1/stages)."
                  },
                  "audience_sources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads from these sources."
                  },
                  "audience_tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads with one of these tags: ids from GET /v1/tags."
                  },
                  "audience_created_within_days": {
                    "type": "number",
                    "description": "Only leads added in the last N days (1-3650), or null."
                  },
                  "audience_skip_booked": {
                    "type": "boolean",
                    "description": "Skip leads with an appointment on the calendar. Default true."
                  },
                  "rolling": {
                    "type": "boolean",
                    "description": "Keep adding new leads that match while it runs. Default true."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "The agent's name, up to 80 characters."
                  },
                  "goal": {
                    "type": "string",
                    "description": "What the call is for.",
                    "enum": [
                      "book_appointment",
                      "qualify",
                      "confirm_interest"
                    ]
                  },
                  "offer": {
                    "type": "string",
                    "description": "What the call is about, up to 4000 characters."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "The opening line, up to 2000 characters."
                  },
                  "script": {
                    "type": "string",
                    "description": "What to say and ask, in order, up to 8000 characters."
                  },
                  "extra_instructions": {
                    "type": "string",
                    "description": "Anything else the agent should know, up to 20,000 characters."
                  },
                  "transfer_number": {
                    "type": "string",
                    "description": "A person's number the agent can put the lead through to, with its country code (+14155550123). Not the line the campaign calls from. null = no transfers."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "The calendar the agent books into (GET /v1/calendars)."
                  },
                  "max_call_seconds": {
                    "type": "number",
                    "description": "Longest call, 60-900 seconds."
                  },
                  "voicemail_action": {
                    "type": "string",
                    "description": "On voicemail.",
                    "enum": [
                      "hangup",
                      "leave_message"
                    ]
                  },
                  "voicemail_message": {
                    "type": "string",
                    "description": "What to leave, up to 2000 characters."
                  },
                  "start_at": {
                    "type": "string",
                    "description": "Earliest moment it may call once started (ISO date and time)."
                  },
                  "run_days": {
                    "type": "number",
                    "description": "How many days it runs once started, 1-90 (default 30)."
                  },
                  "call_days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Days it may call: sun, mon, tue, wed, thu, fri, sat (default mon-fri)."
                  },
                  "call_window_start": {
                    "type": "string",
                    "description": "HH:MM (default 09:00)."
                  },
                  "call_window_end": {
                    "type": "string",
                    "description": "HH:MM (default 18:00)."
                  },
                  "max_attempts_per_lead": {
                    "type": "number",
                    "description": "1-12 (default 4)."
                  },
                  "hours_between_attempts": {
                    "type": "number",
                    "description": "1-72 (default 4)."
                  },
                  "daily_call_cap": {
                    "type": "number",
                    "description": "Calls a day, 1-1000 (default 100)."
                  },
                  "max_concurrent_calls": {
                    "type": "number",
                    "description": "Calls at once, 1-5 (default 1)."
                  },
                  "stop_on_reply": {
                    "type": "boolean",
                    "description": "Stop calling a lead who replies. Default true."
                  },
                  "spend_cap_credits": {
                    "type": "number",
                    "description": "Stop after this many credits, or null for no cap."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Winter check-in",
                "audience_statuses": [
                  "contacted"
                ],
                "audience_created_within_days": 90,
                "goal": "book_appointment",
                "offer": "a free winter roof inspection",
                "call_days": [
                  "mon",
                  "tue",
                  "wed",
                  "thu"
                ],
                "call_window_start": "10:00",
                "call_window_end": "17:00",
                "daily_call_cap": 40
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "list_call_campaigns",
        "tags": [
          "Calls"
        ],
        "summary": "AI calling campaigns and their progress",
        "description": "Leads, calls placed and connected, bookings, and credits used against the spend cap.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only this status.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "running",
                "paused",
                "completed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-campaigns/{campaign_id}": {
      "get": {
        "operationId": "get_call_campaign",
        "tags": [
          "Calls"
        ],
        "summary": "One AI calling campaign",
        "description": "The campaign whole: who it calls, what the agent says, when it calls, its progress (`leads_total`, `calls_placed`, `calls_connected`, bookings, `credits_used`) and `audience_now`: how many leads its rules match right now (who starting it would call).\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_call_campaign",
        "tags": [
          "Calls"
        ],
        "summary": "Change an AI calling campaign",
        "description": "Changes only the fields sent (the fields of `POST /v1/call-campaigns`). Never its status: pausing is `POST /v1/call-campaigns/{campaign_id}/pause`, starting and resuming are done in the app.\n\nWhile the campaign is running, who it calls (the audience_ fields and rolling) can't change, because a running campaign calls whoever matches: 409, pause it first.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The campaign's name, up to 120 characters."
                  },
                  "audience_statuses": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Built-in stages to call: new, contacted, qualified, booked, partial. Empty with no audience_stages = every open lead."
                  },
                  "audience_stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Custom stage keys to call (GET /v1/stages)."
                  },
                  "audience_sources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads from these sources."
                  },
                  "audience_tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads with one of these tags: ids from GET /v1/tags."
                  },
                  "audience_created_within_days": {
                    "type": "number",
                    "description": "Only leads added in the last N days (1-3650), or null."
                  },
                  "audience_skip_booked": {
                    "type": "boolean",
                    "description": "Skip leads with an appointment on the calendar. Default true."
                  },
                  "rolling": {
                    "type": "boolean",
                    "description": "Keep adding new leads that match while it runs. Default true."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "The agent's name, up to 80 characters."
                  },
                  "goal": {
                    "type": "string",
                    "description": "What the call is for.",
                    "enum": [
                      "book_appointment",
                      "qualify",
                      "confirm_interest"
                    ]
                  },
                  "offer": {
                    "type": "string",
                    "description": "What the call is about, up to 4000 characters."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "The opening line, up to 2000 characters."
                  },
                  "script": {
                    "type": "string",
                    "description": "What to say and ask, in order, up to 8000 characters."
                  },
                  "extra_instructions": {
                    "type": "string",
                    "description": "Anything else the agent should know, up to 20,000 characters."
                  },
                  "transfer_number": {
                    "type": "string",
                    "description": "A person's number the agent can put the lead through to, with its country code (+14155550123). Not the line the campaign calls from. null = no transfers."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "The calendar the agent books into (GET /v1/calendars)."
                  },
                  "max_call_seconds": {
                    "type": "number",
                    "description": "Longest call, 60-900 seconds."
                  },
                  "voicemail_action": {
                    "type": "string",
                    "description": "On voicemail.",
                    "enum": [
                      "hangup",
                      "leave_message"
                    ]
                  },
                  "voicemail_message": {
                    "type": "string",
                    "description": "What to leave, up to 2000 characters."
                  },
                  "start_at": {
                    "type": "string",
                    "description": "Earliest moment it may call once started (ISO date and time)."
                  },
                  "run_days": {
                    "type": "number",
                    "description": "How many days it runs once started, 1-90 (default 30)."
                  },
                  "call_days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Days it may call: sun, mon, tue, wed, thu, fri, sat (default mon-fri)."
                  },
                  "call_window_start": {
                    "type": "string",
                    "description": "HH:MM (default 09:00)."
                  },
                  "call_window_end": {
                    "type": "string",
                    "description": "HH:MM (default 18:00)."
                  },
                  "max_attempts_per_lead": {
                    "type": "number",
                    "description": "1-12 (default 4)."
                  },
                  "hours_between_attempts": {
                    "type": "number",
                    "description": "1-72 (default 4)."
                  },
                  "daily_call_cap": {
                    "type": "number",
                    "description": "Calls a day, 1-1000 (default 100)."
                  },
                  "max_concurrent_calls": {
                    "type": "number",
                    "description": "Calls at once, 1-5 (default 1)."
                  },
                  "stop_on_reply": {
                    "type": "boolean",
                    "description": "Stop calling a lead who replies. Default true."
                  },
                  "spend_cap_credits": {
                    "type": "number",
                    "description": "Stop after this many credits, or null for no cap."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "script": "Ask how the roof held up this winter, then offer the free inspection.",
                "daily_call_cap": 60
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_call_campaign",
        "tags": [
          "Calls"
        ],
        "summary": "Delete an AI calling campaign",
        "description": "Deletes the campaign. Calls still queued for it are dropped first, so a deleted campaign never dials. Calls already made stay in the call log.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-campaigns/audience": {
      "post": {
        "operationId": "preview_call_campaign_audience",
        "tags": [
          "Calls"
        ],
        "summary": "Count who a calling campaign would call",
        "description": "A count only, nobody is called: how many leads a set of audience rules would call right now (`would_call`), by the same rules a campaign enrols with, and who is held back: `handed_to_a_person` (the AI passed them to the team), `asked_not_to_be_called`, `paused_by_the_team`, `bad_number`, `no_phone`, `has_an_appointment`.\n\n- `by_stage` splits `would_call` when more than one stage is picked.\n- With no rules sent it counts every open lead with no appointment.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "audience_statuses": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Built-in stages: new, contacted, qualified, booked, partial."
                  },
                  "audience_stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Custom stage keys."
                  },
                  "audience_sources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads from these sources."
                  },
                  "audience_tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads with one of these tags (ids)."
                  },
                  "audience_created_within_days": {
                    "type": "number",
                    "description": "Only leads added in the last N days."
                  },
                  "audience_skip_booked": {
                    "type": "boolean",
                    "description": "Skip leads with an appointment on the calendar. Default true."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "audience_statuses": [
                  "new",
                  "contacted"
                ],
                "audience_created_within_days": 60
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "audience": {
                      "would_call": 212,
                      "held_back": {
                        "handed_to_a_person": 4,
                        "asked_not_to_be_called": 9,
                        "paused_by_the_team": 2,
                        "bad_number": 11,
                        "no_phone": 18,
                        "has_an_appointment": 27
                      },
                      "by_stage": {
                        "new": 140,
                        "contacted": 72
                      }
                    },
                    "note": "A count only: nobody is called. Won, lost and spam leads are never called."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns": {
      "get": {
        "operationId": "list_text_campaigns",
        "tags": [
          "Messaging"
        ],
        "summary": "List AI texting campaigns",
        "description": "A sub-account's AI texting campaigns, newest first: who each texts, its goal and instructions, its texting hours, why it is paused or held (`paused_because`, `on_hold`), what keeps a draft from starting (`start_problems`: no texting number, rules that match nobody, nothing for the AI to say) and where its people stand (people: total, queued, waiting, replied, goal, `needs_you`, `opted_out`, `no_reply`, texted, `replied_ever`, `texts_sent`, `first_today`, `next_send_at`, `goal_reached`). Drafts carry `matching_now`: how many people starting it would text.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only campaigns in this status.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "running",
                "paused",
                "completed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "Create an AI texting campaign (always a draft)",
        "description": "Saves a new texting campaign as a draft: nobody is texted until `POST /v1/text-campaigns/{campaign_id}/start`.\n\n- The AI writes each person's first text from what's on file (or sends your `first_message`), follows up with the ones who don't answer, and answers every reply with this campaign's goal and instructions, which win over the account's AI settings for these conversations (even with the account's AI texts off).\n- A preset fills the name, goal and who it texts (`not_booked`: leads who never booked; `win_back`: Lost leads quiet 30+ days; `past_customers`; `gone_quiet`); with no preset and no audience it texts leads who never booked.\n- Every value is checked and a wrong one refused with the allowed ones.\n- The calendar and tags must be the sub-account's own.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "preset": {
                    "type": "string",
                    "description": "A ready-made audience (GET /v1/text-campaigns/setup).",
                    "enum": [
                      "not_booked",
                      "win_back",
                      "past_customers",
                      "gone_quiet",
                      "custom"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters. Default: the preset's name."
                  },
                  "audience": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Who it texts: stages (board columns: new, contacted, partial, qualified, booked, won, lost or a custom stage key; spam is never texted), sources, tag_ids (GET /v1/tags), skip_booked (default true), customers exclude | include | only (existing customers and Won leads), created_within_days, older_than_days, quiet_days (nothing either way for N days), skip_texted_days. A rule sent is laid over the preset's (or the campaign's) own."
                  },
                  "rolling": {
                    "type": "boolean",
                    "description": "Keep adding new leads who match while it runs. Default false."
                  },
                  "goal": {
                    "type": "string",
                    "description": "What the AI works towards in replies. Default book.",
                    "enum": [
                      "book",
                      "collect",
                      "reply"
                    ]
                  },
                  "offer": {
                    "type": "string",
                    "description": "What the campaign is about, up to 1,500 characters."
                  },
                  "instructions": {
                    "type": "string",
                    "description": "How the AI should text these people, up to 4,000 characters. Wins over the account's AI instructions in these conversations."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "The name the AI texts as, up to 40 characters. Default the account's."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "The calendar it books into (GET /v1/calendars). Default the account's."
                  },
                  "reply_mode": {
                    "type": "string",
                    "description": "auto answers replies by itself; approve has each reply wait for the team. Default auto.",
                    "enum": [
                      "auto",
                      "approve"
                    ]
                  },
                  "first_message_mode": {
                    "type": "string",
                    "description": "ai writes each person's first text; template sends first_message. Default ai.",
                    "enum": [
                      "ai",
                      "template"
                    ]
                  },
                  "first_message": {
                    "type": "string",
                    "description": "Your own first text, up to 480 characters, with {first_name}, {business} and the other variables of GET /v1/text-campaigns/setup."
                  },
                  "opt_out_line": {
                    "type": "boolean",
                    "description": "End the first text with Reply STOP to opt out. Default true."
                  },
                  "follow_ups": {
                    "type": "number",
                    "description": "Follow-ups to people who don't answer, 0-4. Default 2."
                  },
                  "follow_up_gap_days": {
                    "type": "number",
                    "description": "Days between texts, 1-14. Default 2."
                  },
                  "follow_up_texts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Your own follow-ups, in order; \"\" lets the AI write that one."
                  },
                  "nudge_quiet": {
                    "type": "boolean",
                    "description": "One nudge when a conversation stops on our side for a day. Default true."
                  },
                  "send_days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Days it may text: mon, tue, wed, thu, fri, sat, sun. Default mon-sat."
                  },
                  "send_start": {
                    "type": "string",
                    "description": "HH:MM in the sub-account's time zone. Default 09:00."
                  },
                  "send_end": {
                    "type": "string",
                    "description": "HH:MM, at least an hour after send_start. Default 19:00."
                  },
                  "daily_cap": {
                    "type": "number",
                    "description": "New people texted a day, 1-1000. Default 100."
                  },
                  "run_days": {
                    "type": "number",
                    "description": "How many days it runs once started, 1-120. Default 30."
                  },
                  "start_at": {
                    "type": "string",
                    "description": "Earliest moment it may text once started (ISO date and time)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "preset": "win_back",
                "offer": "15% off any repair this month",
                "instructions": "Lead with the special. Short and casual."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "campaign": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Win back lost leads",
                      "status": "draft",
                      "status_label": "Draft",
                      "paused_because": null,
                      "on_hold": null,
                      "preset": "win_back",
                      "audience": {
                        "stages": [
                          "lost"
                        ],
                        "sources": [],
                        "tag_ids": [],
                        "skip_booked": true,
                        "customers": "exclude",
                        "created_within_days": null,
                        "older_than_days": null,
                        "quiet_days": 30,
                        "skip_texted_days": 14
                      },
                      "rolling": false,
                      "goal": "book",
                      "goal_label": "Book an appointment",
                      "offer": "15% off any repair this month",
                      "instructions": "Lead with the special. Short and casual.",
                      "agent_name": null,
                      "calendar_id": null,
                      "reply_mode": "auto",
                      "first_message_mode": "ai",
                      "first_message": null,
                      "opt_out_line": true,
                      "follow_ups": 2,
                      "follow_up_gap_days": 2,
                      "follow_up_texts": [],
                      "nudge_quiet": true,
                      "send_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri",
                        "sat"
                      ],
                      "send_start": "09:00",
                      "send_end": "19:00",
                      "daily_cap": 100,
                      "run_days": 30,
                      "start_at": null,
                      "started_at": null,
                      "ends_at": null,
                      "completed_at": null,
                      "last_run_at": null,
                      "created_at": "2026-11-20T15:00:00Z",
                      "updated_at": "2026-11-20T15:00:00Z",
                      "start_problems": []
                    },
                    "note": "Saved as a draft: nobody is texted. POST /v1/text-campaigns/{id}/start (confirm: true) starts it."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/setup": {
      "get": {
        "operationId": "get_text_campaign_setup",
        "tags": [
          "Messaging"
        ],
        "summary": "What a texting campaign starts from",
        "description": "The sub-account's texting number (`has_texting_number`: a campaign can't start without one), daily texting limit, its account-level AI (`texts_on`, goal, `agent_name`, `reply_mode`, instructions: what a campaign's own settings win over), prices in credits (a text, an AI reply), the ready-made audiences with how many people each would text now (presets[].`matching_now`), the goals and the variables a text may use.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/audience": {
      "post": {
        "operationId": "preview_text_campaign_audience",
        "tags": [
          "Messaging"
        ],
        "summary": "Count who a texting campaign would text",
        "description": "A count only, nobody is texted: how many people a set of rules would text right now (`would_text`), by the same rule a campaign enrols with, and who is held back and why (`held_back`: `no_phone`, `cant_text`, team: the AI is paused for them, `other_campaign`: in another live texting campaign, recent: heard from you recently; `held_back_words` says it in words), with up to three first names it would text. Rules: a preset, a campaign's own (`campaign_id`), or audience; audience is laid over either.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "preset": {
                    "type": "string",
                    "description": "Start from a ready-made audience.",
                    "enum": [
                      "not_booked",
                      "win_back",
                      "past_customers",
                      "gone_quiet",
                      "custom"
                    ]
                  },
                  "campaign_id": {
                    "type": "string",
                    "description": "Start from this campaign's own rules."
                  },
                  "audience": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Who it texts: stages (board columns: new, contacted, partial, qualified, booked, won, lost or a custom stage key; spam is never texted), sources, tag_ids (GET /v1/tags), skip_booked (default true), customers exclude | include | only (existing customers and Won leads), created_within_days, older_than_days, quiet_days (nothing either way for N days), skip_texted_days. A rule sent is laid over the preset's (or the campaign's) own."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "preset": "not_booked",
                "audience": {
                  "quiet_days": 7
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "would_text": 184,
                    "held_back": {
                      "no_phone": 12,
                      "cant_text": 9,
                      "recent": 31
                    },
                    "held_back_words": {
                      "no_phone": "no phone number",
                      "cant_text": "can't be texted (opted out or a bad number)",
                      "recent": "heard from you recently"
                    },
                    "sample_first_names": [
                      "Maria",
                      "Dan",
                      "Priya"
                    ],
                    "audience": {
                      "stages": [
                        "new",
                        "contacted",
                        "partial"
                      ],
                      "sources": [],
                      "tag_ids": [],
                      "skip_booked": true,
                      "customers": "exclude",
                      "created_within_days": null,
                      "older_than_days": null,
                      "quiet_days": 7,
                      "skip_texted_days": 2
                    },
                    "note": "A count only: nobody is texted. Spam is never texted; Won and Lost leads only when their stages are picked."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/preview": {
      "post": {
        "operationId": "preview_text_campaign_text",
        "tags": [
          "Messaging"
        ],
        "summary": "A sample text for one real lead",
        "description": "Writes the text a campaign would send one real lead, as the editor's phone preview does: the campaign's saved settings (`campaign_id`) with any campaign field sent laid over them, or a draft of fields alone.\n\n- step first (default) or `follow_up` (`follow_up`: which one, 1-4; earlier: the texts it would already have sent).\n- `lead_id` picks whose text; left out, someone the campaign would text.\n- Nothing is saved or sent.\n- When the AI can't write it, text is null and `could_not_write` says why.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "campaign_id": {
                    "type": "string",
                    "description": "Use this campaign's saved settings."
                  },
                  "step": {
                    "type": "string",
                    "description": "Which text. Default first.",
                    "enum": [
                      "first",
                      "follow_up"
                    ]
                  },
                  "follow_up": {
                    "type": "number",
                    "description": "Which follow-up, 1-4."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "Whose text."
                  },
                  "earlier": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "For a follow-up: up to 4 texts the campaign already sent them."
                  },
                  "offer": {
                    "type": "string",
                    "description": "Any field of POST /v1/text-campaigns overrides the saved one for this sample."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "campaign_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "text": "Hi Maria, it's Sam at Delgado Garage Doors. We're doing 15% off any repair this month. Want me to find you a time this week? Reply STOP to opt out.",
                    "written_by": "ai",
                    "lead": {
                      "id": "uuid",
                      "name": "Maria Lopez"
                    },
                    "note": "A sample for one real lead: nothing was saved or sent. Each person gets their own text when the campaign runs."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/{campaign_id}": {
      "get": {
        "operationId": "get_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "One AI texting campaign",
        "description": "The campaign whole (the fields of `POST /v1/text-campaigns`), where its people stand (people), whether it is inside its texting hours now (`texting_now`, `window_opens_at`), `matching_now` and `held_back_now`: who its rules match right now, `start_problems`: what would stop a start (no texting number, a draft whose rules match nobody, nothing for the AI to say), and `what_start_does`: what starting it would do, in words to read to the person before they say yes.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "Change an AI texting campaign",
        "description": "Changes only the fields sent (the fields of `POST /v1/text-campaigns`; audience rules are laid over the campaign's own).\n\n- Never its status: that is start, pause and stop.\n- While the campaign is texting, who it texts (audience, rolling) can't change: 409, pause it first.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "preset": {
                    "type": "string",
                    "description": "A ready-made audience (GET /v1/text-campaigns/setup).",
                    "enum": [
                      "not_booked",
                      "win_back",
                      "past_customers",
                      "gone_quiet",
                      "custom"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters. Default: the preset's name."
                  },
                  "audience": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Who it texts: stages (board columns: new, contacted, partial, qualified, booked, won, lost or a custom stage key; spam is never texted), sources, tag_ids (GET /v1/tags), skip_booked (default true), customers exclude | include | only (existing customers and Won leads), created_within_days, older_than_days, quiet_days (nothing either way for N days), skip_texted_days. A rule sent is laid over the preset's (or the campaign's) own."
                  },
                  "rolling": {
                    "type": "boolean",
                    "description": "Keep adding new leads who match while it runs. Default false."
                  },
                  "goal": {
                    "type": "string",
                    "description": "What the AI works towards in replies. Default book.",
                    "enum": [
                      "book",
                      "collect",
                      "reply"
                    ]
                  },
                  "offer": {
                    "type": "string",
                    "description": "What the campaign is about, up to 1,500 characters."
                  },
                  "instructions": {
                    "type": "string",
                    "description": "How the AI should text these people, up to 4,000 characters. Wins over the account's AI instructions in these conversations."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "The name the AI texts as, up to 40 characters. Default the account's."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "The calendar it books into (GET /v1/calendars). Default the account's."
                  },
                  "reply_mode": {
                    "type": "string",
                    "description": "auto answers replies by itself; approve has each reply wait for the team. Default auto.",
                    "enum": [
                      "auto",
                      "approve"
                    ]
                  },
                  "first_message_mode": {
                    "type": "string",
                    "description": "ai writes each person's first text; template sends first_message. Default ai.",
                    "enum": [
                      "ai",
                      "template"
                    ]
                  },
                  "first_message": {
                    "type": "string",
                    "description": "Your own first text, up to 480 characters, with {first_name}, {business} and the other variables of GET /v1/text-campaigns/setup."
                  },
                  "opt_out_line": {
                    "type": "boolean",
                    "description": "End the first text with Reply STOP to opt out. Default true."
                  },
                  "follow_ups": {
                    "type": "number",
                    "description": "Follow-ups to people who don't answer, 0-4. Default 2."
                  },
                  "follow_up_gap_days": {
                    "type": "number",
                    "description": "Days between texts, 1-14. Default 2."
                  },
                  "follow_up_texts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Your own follow-ups, in order; \"\" lets the AI write that one."
                  },
                  "nudge_quiet": {
                    "type": "boolean",
                    "description": "One nudge when a conversation stops on our side for a day. Default true."
                  },
                  "send_days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Days it may text: mon, tue, wed, thu, fri, sat, sun. Default mon-sat."
                  },
                  "send_start": {
                    "type": "string",
                    "description": "HH:MM in the sub-account's time zone. Default 09:00."
                  },
                  "send_end": {
                    "type": "string",
                    "description": "HH:MM, at least an hour after send_start. Default 19:00."
                  },
                  "daily_cap": {
                    "type": "number",
                    "description": "New people texted a day, 1-1000. Default 100."
                  },
                  "run_days": {
                    "type": "number",
                    "description": "How many days it runs once started, 1-120. Default 30."
                  },
                  "start_at": {
                    "type": "string",
                    "description": "Earliest moment it may text once started (ISO date and time)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "instructions": "Offer two times this week. Never bring up price first.",
                "daily_cap": 60
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "Delete an AI texting campaign",
        "description": "Deletes the campaign and its list of people. Texts already sent stay in each conversation, and its people's replies go back to the account's AI settings.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/{campaign_id}/duplicate": {
      "post": {
        "operationId": "duplicate_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "Copy an AI texting campaign",
        "description": "A draft copy of the campaign's settings, named \"(copy)\": nobody is texted until it is started.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/{campaign_id}/start": {
      "post": {
        "operationId": "start_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "Start or resume an AI texting campaign (texts real people)",
        "description": "Starts a draft, resumes a paused campaign, or runs a finished one again with a fresh run window: everyone who matches its rules now is added and texted inside its texting hours, at most `daily_cap` new people a day.\n\n> **Warning:** Texts real people from the sub-account's number and spends credits, so confirm: true is required; an assistant must tell the person which campaign, how many people it would text (`matching_now` on `GET /v1/text-campaigns/{campaign_id}`) and when, and get a clear yes first.\n\n- Refused (409) when it is already texting, the sub-account has no texting number, nobody matches, or something it needs is missing (`start_problems`); (402) when the account is out of credits.\n- Answers `added_people`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "boolean",
                    "description": "Must be true: real texts will go out and credits are spent."
                  }
                },
                "required": [
                  "confirm"
                ],
                "additionalProperties": true
              },
              "example": {
                "confirm": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/{campaign_id}/pause": {
      "post": {
        "operationId": "pause_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "Pause an AI texting campaign",
        "description": "No more texts until it is started again. Replies are still answered by the campaign's AI. Only a running campaign can be paused (409).\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/{campaign_id}/stop": {
      "post": {
        "operationId": "stop_text_campaign",
        "tags": [
          "Messaging"
        ],
        "summary": "Finish an AI texting campaign",
        "description": "Finishes it: nobody else is texted, people waiting for a follow-up are marked no reply, and conversations already going keep the campaign's AI. A draft is deleted instead (409). Start runs it again.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/{campaign_id}/people": {
      "get": {
        "operationId": "list_text_campaign_people",
        "tags": [
          "Messaging"
        ],
        "summary": "Who is in an AI texting campaign",
        "description": "50 people at a time: each one's lead, state (queued: up next, waiting: texted, replied, goal, `needs_you`: with the team, `opted_out`, `no_reply`, stopped, skipped, failed) in words, why they left, texts and follow-ups sent, when the next text goes, their last text and last reply.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "Default all.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "active",
                "replied",
                "goal",
                "needs_you",
                "no_reply",
                "out"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "A name or phone.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many (next_offset of the last page).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/text-campaigns/{campaign_id}/people/{lead_id}": {
      "delete": {
        "operationId": "remove_text_campaign_person",
        "tags": [
          "Messaging"
        ],
        "summary": "Take a person out of an AI texting campaign",
        "description": "The campaign texts them no more. Someone already finished with it answers removed: false.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-calling": {
      "get": {
        "operationId": "get_ai_calling",
        "tags": [
          "Calls"
        ],
        "summary": "The AI caller's settings",
        "description": "The always-on AI caller of a sub-account (Settings > AI calling): whether it is on, whether it calls new leads by itself, what it says and when it calls. Shows the app's defaults until someone saves. The voice is picked in the app.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ai_calling": {
                      "workspace_id": "uuid",
                      "enabled": false,
                      "auto_enroll_new_leads": false,
                      "agent_name": "Alex",
                      "goal": "book_appointment",
                      "greeting": null,
                      "offer": null,
                      "extra_instructions": null,
                      "call_days": [
                        "mon",
                        "tue",
                        "wed",
                        "thu",
                        "fri",
                        "sat"
                      ],
                      "call_window_start": "08:00",
                      "call_window_end": "19:00",
                      "first_call_delay_minutes": 2,
                      "max_attempts_per_day": 2,
                      "hours_between_attempts": 3,
                      "max_total_attempts": 10,
                      "attempt_jitter_minutes": 20,
                      "taper_enabled": true,
                      "max_call_seconds": 300,
                      "stop_on_reply": true,
                      "voicemail_action": "hangup",
                      "voicemail_message": null,
                      "eligible_sources": [],
                      "eligible_statuses": [],
                      "default_calendar_id": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_ai_calling",
        "tags": [
          "Calls"
        ],
        "summary": "Change the AI caller's settings",
        "description": "Changes only the settings sent.\n\n- With enabled and `auto_enroll_new_leads` both true, new leads that match `eligible_sources` and `eligible_statuses` (empty = all) are called by the AI caller by itself, `first_call_delay_minutes` after they come in, inside `call_days` and the call window; those calls cost credits like any AI call, so turn them on only when the business asked for it.\n- `default_calendar_id` must be one of the sub-account's calendars.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "The AI caller on or off."
                  },
                  "auto_enroll_new_leads": {
                    "type": "boolean",
                    "description": "Call new leads by itself."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "Up to 80 characters."
                  },
                  "goal": {
                    "type": "string",
                    "description": "What a call is for.",
                    "enum": [
                      "book_appointment",
                      "qualify",
                      "confirm_interest"
                    ]
                  },
                  "greeting": {
                    "type": "string",
                    "description": "The opening line, up to 2000 characters; null for the usual one."
                  },
                  "offer": {
                    "type": "string",
                    "description": "What the call is about, up to 4000 characters."
                  },
                  "extra_instructions": {
                    "type": "string",
                    "description": "Up to 20,000 characters."
                  },
                  "call_days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "sun, mon, tue, wed, thu, fri, sat."
                  },
                  "call_window_start": {
                    "type": "string",
                    "description": "HH:MM in the sub-account's time zone."
                  },
                  "call_window_end": {
                    "type": "string",
                    "description": "HH:MM."
                  },
                  "first_call_delay_minutes": {
                    "type": "number",
                    "description": "0-1440."
                  },
                  "max_attempts_per_day": {
                    "type": "number",
                    "description": "1-10."
                  },
                  "hours_between_attempts": {
                    "type": "number",
                    "description": "1-72."
                  },
                  "max_total_attempts": {
                    "type": "number",
                    "description": "1-20."
                  },
                  "attempt_jitter_minutes": {
                    "type": "number",
                    "description": "0-60: tries land a little before or after the hour."
                  },
                  "taper_enabled": {
                    "type": "boolean",
                    "description": "Space later tries further apart."
                  },
                  "max_call_seconds": {
                    "type": "number",
                    "description": "60-900."
                  },
                  "stop_on_reply": {
                    "type": "boolean",
                    "description": "Stop calling a lead who replies."
                  },
                  "voicemail_action": {
                    "type": "string",
                    "description": "On voicemail.",
                    "enum": [
                      "hangup",
                      "leave_message"
                    ]
                  },
                  "voicemail_message": {
                    "type": "string",
                    "description": "Up to 2000 characters."
                  },
                  "eligible_sources": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads from these sources; empty = all."
                  },
                  "eligible_statuses": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads in these stages; empty = all."
                  },
                  "default_calendar_id": {
                    "type": "string",
                    "description": "The calendar the agent books into, or null."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "agent_name": "Riley",
                "call_window_start": "09:00",
                "call_window_end": "18:00",
                "max_total_attempts": 6
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/contract-templates": {
      "post": {
        "operationId": "create_contract_template",
        "tags": [
          "Contracts"
        ],
        "summary": "Create a contract template",
        "description": "A new template in the sub-account's Contracts (Tools > Contracts > Templates), ready for `POST /v1/contracts`.\n\n- Send the text as `body_html` (HTML) or body (plain text with markdown: # headings, - or 1. lists, **bold**, *italic*).\n- Write `{{client_name}}`, `{{price}}`, `{{start_date}}` and the like where a value goes: each becomes a blank (variables / blanks in the answer) filled when a contract is made.\n- HTML is cleaned before it is saved, to exactly what the signing page shows: headings, paragraphs, lists, tables, bold / italic / underline, links (https, mailto, tel), https pictures, drawn-signature SVG paths and simple inline styles (alignment, colors, margins, fonts) stay; scripts, styles, forms, frames, event handlers and javascript: or data: links are removed, and unknown tags keep only their words.\n- The answer's `body_html` is what was saved.\n- Up to 200,000 characters.\n- Optional step after signing: `booking_enabled` with `booking_calendar_id` (one of the sub-account's calendars), `booking_heading`, `booking_message`.\n\nWho can call it: Any member of the sub-account, as on the Contracts page.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "The template's name, up to 160 characters."
                  },
                  "body_html": {
                    "type": "string",
                    "description": "The contract's text as HTML (cleaned before saving). Or body."
                  },
                  "body": {
                    "type": "string",
                    "description": "The contract's text as plain text with markdown. Or body_html."
                  },
                  "description": {
                    "type": "string",
                    "description": "What it is for, up to 500 characters."
                  },
                  "category": {
                    "type": "string",
                    "description": "A label to group templates by, up to 60 characters."
                  },
                  "booking_enabled": {
                    "type": "boolean",
                    "description": "After signing, offer a calendar to book on. Needs booking_calendar_id."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "The calendar to book on (GET /v1/calendars)."
                  },
                  "booking_heading": {
                    "type": "string",
                    "description": "Heading over the calendar, up to 120 characters."
                  },
                  "booking_message": {
                    "type": "string",
                    "description": "A line under it, up to 600 characters."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Roofing agreement",
                "category": "Roofing",
                "body": "# Roofing agreement\n\nThis agreement is between {{business_name}} and {{client_name}}.\n\n## Scope\n\n- Replace the roof at {{client_address}}\n- Start on {{start_date}}\n\n## Price\n\n**{{price}}**, half due before work starts."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "template": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Roofing agreement",
                      "description": null,
                      "category": "Roofing",
                      "variables": [
                        "business_name",
                        "client_name",
                        "client_address",
                        "start_date",
                        "price"
                      ],
                      "blanks": [
                        "business_name",
                        "client_name",
                        "client_address",
                        "start_date",
                        "price"
                      ],
                      "body_html": "<h2>Roofing agreement</h2>\n<p>This agreement is between {{business_name}} and {{client_name}}.</p>",
                      "booking_enabled": false,
                      "booking_calendar_id": null,
                      "booking_heading": null,
                      "booking_message": null,
                      "created_at": "2026-11-15T16:00:00Z",
                      "updated_at": "2026-11-15T16:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "get": {
        "operationId": "list_contract_templates",
        "tags": [
          "Contracts"
        ],
        "summary": "Contract templates",
        "description": "The sub-account's templates with their `{{blanks}}`. Most fill in by themselves on a new contract (`client_name`, `client_email`, `client_phone`, `client_address`, `business_name`, date); send values for the rest.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_body",
            "in": "query",
            "required": false,
            "description": "Include each template's text (body_html).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "templates": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Service agreement",
                        "description": null,
                        "category": null,
                        "variables": [
                          "client_name",
                          "start_date",
                          "price"
                        ],
                        "blanks": [
                          "client_name",
                          "start_date",
                          "price"
                        ],
                        "booking_enabled": false,
                        "booking_calendar_id": null,
                        "created_at": "2026-10-01T00:00:00Z",
                        "updated_at": "2026-10-20T00:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/contract-templates/{template_id}": {
      "get": {
        "operationId": "get_contract_template",
        "tags": [
          "Contracts"
        ],
        "summary": "One contract template",
        "description": "The template with its text (`body_html`), its `{{blanks}}` and its booking step. Only the sub-account's own templates: the agency's are not reachable here.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "description": "Template id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_contract_template",
        "tags": [
          "Contracts"
        ],
        "summary": "Change a contract template",
        "description": "Changes only what is sent: name, description, category, the text (`body_html` or body, cleaned like on create; the blanks are worked out again) or the booking step (send `booking_enabled` with it; `booking_enabled` false turns it off). Contracts already made from the template keep their own text.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "description": "Template id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 160 characters."
                  },
                  "body_html": {
                    "type": "string",
                    "description": "The new text as HTML. Or body."
                  },
                  "body": {
                    "type": "string",
                    "description": "The new text as plain text with markdown. Or body_html."
                  },
                  "description": {
                    "type": "string",
                    "description": "Up to 500 characters; null clears it."
                  },
                  "category": {
                    "type": "string",
                    "description": "Up to 60 characters; null clears it."
                  },
                  "booking_enabled": {
                    "type": "boolean",
                    "description": "The booking step on or off; send it with any booking field."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "The calendar to book on."
                  },
                  "booking_heading": {
                    "type": "string",
                    "description": "Up to 120 characters."
                  },
                  "booking_message": {
                    "type": "string",
                    "description": "Up to 600 characters."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Roofing agreement (2027)",
                "description": "For full roof replacements"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_contract_template",
        "tags": [
          "Contracts"
        ],
        "summary": "Delete a contract template",
        "description": "Deletes the template. Contracts already made from it are not touched: each keeps its own text.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "description": "Template id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/brand-settings": {
      "get": {
        "operationId": "get_brand_settings",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Get a sub-account's CRM brand",
        "description": "Settings > Branding: the logo (also the browser icon), the home-screen app icon, whether the sub-account has its own installable app and its name, the CRM's own name, accent colour and hide-logo switch, and the sign-in page on the business's own domain (headline, text, color, `image_url`). `agency_only` lists the fields only the agency side may change.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_brand_settings",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Update a sub-account's CRM brand",
        "description": "Changes only what is sent; everything else about the brand is kept. `logo_url` is also saved as the browser icon and as the sub-account's logo on lists, invoices and contracts; null removes it (and the app icon with it).\n\n- Links must be public https links.\n- `app_install_enabled`, `app_name`, `brand_name`, `accent_color` and `hide_logo` are the agency's: a client admin gets 403 on them.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "logo_url": {
                    "type": "string",
                    "description": "Logo, an https link (null removes it)."
                  },
                  "app_icon_url": {
                    "type": "string",
                    "description": "The square home-screen icon, an https link. Needs a logo."
                  },
                  "sign_in_page": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ headline (80), text (240), color (hex), image_url (https) }: any of them; null clears one."
                  },
                  "app_install_enabled": {
                    "type": "boolean",
                    "description": "Agency only: the sub-account gets its own Add to Home Screen app."
                  },
                  "app_name": {
                    "type": "string",
                    "description": "Agency only: that app's name, up to 40 characters."
                  },
                  "brand_name": {
                    "type": "string",
                    "description": "Agency only: the name the CRM shows for this sub-account, up to 60 characters."
                  },
                  "accent_color": {
                    "type": "string",
                    "description": "Agency only: a hex colour like #0f172a."
                  },
                  "hide_logo": {
                    "type": "boolean",
                    "description": "Agency only: hide the logo in the CRM's menu."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "logo_url": "https://cdn.example.com/logo.png",
                "sign_in_page": {
                  "headline": "Welcome back",
                  "color": "#0f172a"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/custom-menu": {
      "get": {
        "operationId": "get_custom_menu",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Get the CRM's custom menu links",
        "description": "The custom links in a sub-account's CRM menu: `agency_items` (the agency's, shown in every sub-account, read only here) and items (the sub-account's own), each `{ id, label, kind (link | code), url, mode (embed | new_tab | same_tab), icon, audience (everyone | admins) }` and, for kind code, the pasted embed code. Links for admins only are left out for staff.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_custom_menu",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Set the CRM's custom menu links",
        "description": "Replaces the sub-account's own menu links (the agency's stay).\n\nUp to 12 items, each `{ label (up to 40 characters), url }` for a link (http or https; it may use `{workspace_id}`, `{workspace_name}`, `{user_email}`, `{user_name}`) or `{ label, kind: \"code\", code }` for pasted embed code (up to 20,000 characters, always shown as its own page).\n\nOptional:\n- id (kept so a link's address stays the same)\n- mode (embed (default) | `new_tab` | `same_tab`)\n- icon (favicon (default), link, globe, layout, chart, file, folder, video, book, calendar, chat, cart, star, wrench, briefcase, graduation, or lucide:<IconName>)\n- audience (everyone (default) | admins)\n\nAn empty list removes them all.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The links, in order."
                  }
                },
                "required": [
                  "workspace_id",
                  "items"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "items": [
                  {
                    "label": "Reports",
                    "url": "https://reports.example.com/?account={workspace_id}",
                    "mode": "embed",
                    "icon": "chart",
                    "audience": "admins"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/refer": {
      "get": {
        "operationId": "get_refer_and_earn",
        "tags": [
          "Workspaces"
        ],
        "summary": "A sub-account's referral link and rewards",
        "description": "The sub-account's Refer & earn page: on (false when there is no referral program right now, and nothing else is sent), its link and code, the reward it earns (reward) out of `reward_options`, where it wants payouts sent, how long rewards are earned, the people it referred (paying or not) and its rewards with their status (pending, ready, paid). A sub-account key gets 403 `feature_off` when Refer & earn is hidden from the account's people.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (a sub-account key uses its own).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/crm-connections": {
      "get": {
        "operationId": "list_crm_connections",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "List connected job software and CRM tools",
        "description": "The tools a sub-account connected in Settings > Integrations: provider, connected, `sends_new_leads` and `sends_appointments` (it gets them by itself), `leads_arrive_as`, tags, `source_name`, `reads_status_changes`, `reads_revenue`, `last_error`.\n\n- Never a key.\n- Connecting a tool or changing its key is done in the app.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "connections": [
                      {
                        "id": "uuid",
                        "provider": "nutshell",
                        "connected": true,
                        "status": "connected",
                        "last_error": null,
                        "last_verified_at": "2026-11-12T15:00:00Z",
                        "sends_new_leads": true,
                        "sends_appointments": false,
                        "leads_arrive_as": "lead",
                        "tags": [
                          "website"
                        ],
                        "source_name": null,
                        "reads_status_changes": true,
                        "reads_revenue": false,
                        "last_read_at": null,
                        "updated_at": "2026-11-12T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/crm": {
      "get": {
        "operationId": "get_lead_crm",
        "tags": [
          "CRM leads"
        ],
        "summary": "Which connected tools have a lead",
        "description": "For each tool the sub-account connected: `connection_id`, provider, name, `external_id` (the tool's own id for the lead, null when it doesn't have it), `synced_at`, url (a link to open it there, where the tool's address is known), `last_error` and `auto_push`. Anyone who can open the lead (a technician only their own).\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "The lead.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead_id": "uuid",
                    "tools": [
                      {
                        "connection_id": "uuid",
                        "provider": "nutshell",
                        "name": "Nutshell",
                        "external_id": "1234",
                        "synced_at": "2026-11-12T15:00:00Z",
                        "url": "https://app.nutshell.com/lead/1234",
                        "last_error": null,
                        "auto_push": true
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/push-to-crm": {
      "post": {
        "operationId": "push_lead_to_crm",
        "tags": [
          "CRM leads"
        ],
        "summary": "Send a lead to a connected tool now",
        "description": "The lead panel's Push to CRM: sends the lead to one connected tool even when it doesn't get new leads by itself.\n\n- A tool that already has the lead keeps its record and no second one is made (`already_there` true).\n- pushed false carries the tool's own error.\n- Anyone who can open the lead.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "The lead.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "connection_id": {
                    "type": "string",
                    "description": "The tool (connection_id from GET /v1/leads/{lead_id}/crm or id from GET /v1/crm-connections)."
                  }
                },
                "required": [
                  "connection_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "connection_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-domains": {
      "get": {
        "operationId": "list_email_domains",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "List email sending domains",
        "description": "The sub-account's own sending domains (Settings > Email): verified, `is_default`, and `dns_records` `{ dkim, return_path, dmarc }`, each `{ type, host, value, verified }`: the records to add at the domain's registrar.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "domains": [
                      {
                        "id": "uuid",
                        "domain": "mail.acme.com",
                        "verified": false,
                        "verified_at": null,
                        "is_default": true,
                        "dns_records": {
                          "dkim": {
                            "type": "TXT",
                            "host": "20261101._domainkey.mail.acme.com",
                            "value": "k=rsa; p=...",
                            "verified": false
                          },
                          "return_path": {
                            "type": "CNAME",
                            "host": "pm-bounces.mail.acme.com",
                            "value": "pm.mtasv.net",
                            "verified": false
                          },
                          "dmarc": {
                            "type": "TXT",
                            "host": "_dmarc.mail.acme.com",
                            "value": "v=DMARC1; p=none",
                            "verified": false
                          }
                        },
                        "dmarc_policy": null,
                        "last_checked_at": "2026-11-15T15:00:00Z",
                        "last_check_error": null,
                        "created_at": "2026-11-15T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_email_domain",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Add an email sending domain",
        "description": "Registers a domain for sending the sub-account's emails and answers the DNS records to add. The first one becomes the default. 409 when the domain is already set up, here or in another account.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "domain": {
                    "type": "string",
                    "description": "The domain, like mail.acme.com."
                  }
                },
                "required": [
                  "workspace_id",
                  "domain"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "domain": "mail.acme.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-domains/{domain_id}/verify": {
      "post": {
        "operationId": "verify_email_domain",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Check an email domain's DNS records",
        "description": "Looks the DNS records up again and answers the domain with each record's verified. Emails go from the domain once it is verified. DNS changes can take from a few minutes to an hour.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "description": "The domain (GET /v1/email-domains).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-domains/{domain_id}/default": {
      "post": {
        "operationId": "set_default_email_domain",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Send from this email domain",
        "description": "Makes this the sub-account's default sending domain.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "description": "The domain (GET /v1/email-domains).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-domains/{domain_id}": {
      "delete": {
        "operationId": "delete_email_domain",
        "tags": [
          "Sub-account setup"
        ],
        "summary": "Remove an email sending domain",
        "description": "Removes the domain; the sub-account's emails go from its agency's domain or the shared one again.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "description": "The domain (GET /v1/email-domains).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-agents": {
      "get": {
        "operationId": "list_ai_agents",
        "tags": [
          "AI agent"
        ],
        "summary": "List AI agents",
        "description": "The sub-account's AI agents: named assistants that watch a connected email inbox, sort new mail and answer customers.\n\n- Each has its settings, mailbox (provider gmail | outlook, `account_email`, status; null until an inbox is connected in the app), working (on, with a healthy inbox) and `waiting_for_you` (emails a person has to act on).\n- While AI Agents is in its beta, accounts that are not on it get 404 on every AI agent route.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_ai_agent",
        "tags": [
          "AI agent"
        ],
        "summary": "Create an AI agent",
        "description": "Makes an agent. Only name is required; it starts switched off, in approve mode (every reply waits as a draft).\n\n- It answers email once an inbox is connected to it on its page in the app (a sign-in with Google or Microsoft, which the API can't do) and it is switched on.\n- Up to 50 agents a sub-account.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "The agent's name, up to 60 characters."
                  },
                  "role": {
                    "type": "string",
                    "description": "Its job title (default Email assistant), up to 80 characters."
                  },
                  "avatar_url": {
                    "type": "string",
                    "description": "An https link to its picture."
                  },
                  "instructions": {
                    "type": "string",
                    "description": "How it should answer, up to 6,000 characters."
                  },
                  "signature": {
                    "type": "string",
                    "description": "The sign-off under its emails, up to 600 characters."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "On or off (default off)."
                  },
                  "reply_mode": {
                    "type": "string",
                    "description": "approve: every reply waits as a draft. auto: customer emails are answered straight away, anything unclear still waits.",
                    "enum": [
                      "approve",
                      "auto"
                    ]
                  },
                  "can_book": {
                    "type": "boolean",
                    "description": "May it book appointments (default true)."
                  },
                  "daily_reply_cap": {
                    "type": "number",
                    "description": "Most replies a day, 1-1000 (default 100)."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Ava",
                "role": "Email assistant",
                "instructions": "Keep replies short and friendly. Always offer a time to come out.",
                "signature": "Ava\nCastillo Roofing"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-agents/{agent_id}": {
      "get": {
        "operationId": "get_ai_agent",
        "tags": [
          "AI agent"
        ],
        "summary": "Get an AI agent",
        "description": "One agent: its settings, its inbox and how many emails wait for a person.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "Agent id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_ai_agent",
        "tags": [
          "AI agent"
        ],
        "summary": "Update an AI agent",
        "description": "Changes only what is sent: name, role, `avatar_url`, instructions, signature, enabled, `reply_mode` (approve | auto), `can_book`, `daily_reply_cap` (1-1000). Switching `reply_mode` to auto lets it answer customer emails without anyone reading them first.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "Agent id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name."
                  },
                  "role": {
                    "type": "string",
                    "description": "Job title."
                  },
                  "instructions": {
                    "type": "string",
                    "description": "How it should answer."
                  },
                  "signature": {
                    "type": "string",
                    "description": "Sign-off."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "On or off."
                  },
                  "reply_mode": {
                    "type": "string",
                    "description": "approve or auto.",
                    "enum": [
                      "approve",
                      "auto"
                    ]
                  },
                  "can_book": {
                    "type": "boolean",
                    "description": "May it book appointments."
                  },
                  "daily_reply_cap": {
                    "type": "number",
                    "description": "Most replies a day, 1-1000."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "instructions": "Never quote a price. Offer a free visit instead.",
                "daily_reply_cap": 50
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_ai_agent",
        "tags": [
          "AI agent"
        ],
        "summary": "Delete an AI agent",
        "description": "Deletes the agent. Its inbox connection and its list of emails go with it; contacts and their conversations stay.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "Agent id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-agents/{agent_id}/emails": {
      "get": {
        "operationId": "list_ai_agent_emails",
        "tags": [
          "AI agent"
        ],
        "summary": "List an AI agent's emails",
        "description": "The emails the agent looked at, newest first, and what it did with each: category (customer | owner | ignore), summary, urgent, status (new | working | replied | draft | `needs_you` | skipped | failed | dismissed), `status_reason`, `needs_a_person`, the drafted reply (draft), the reply that went out (reply) and the contact (`lead_id`). Emails made with try are left out unless `include_tests`=true.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "Agent id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "One or more statuses, comma-separated (draft,needs_you,failed = what waits for a person).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_tests",
            "in": "query",
            "required": false,
            "description": "true to include try emails.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-200 (default 50).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-agents/{agent_id}/try": {
      "post": {
        "operationId": "try_ai_agent",
        "tags": [
          "AI agent"
        ],
        "summary": "Try an AI agent on a made-up email",
        "description": "The agent page's Try it: the agent sorts a made-up email and drafts the reply it would write. Nothing is sent, nothing stays in the CRM and nothing is charged. Answers status and the email with its draft.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "Agent id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The email's text."
                  },
                  "from_name": {
                    "type": "string",
                    "description": "Who it is from."
                  },
                  "from_email": {
                    "type": "string",
                    "description": "Their address (default customer@example.com)."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Its subject."
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": true
              },
              "example": {
                "from_name": "Jenna Morales",
                "subject": "Quote?",
                "body": "Hi there, how much do you charge to come out and take a look? Do you have anything open this week?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-agent-emails/{email_id}/approve": {
      "post": {
        "operationId": "approve_ai_agent_email",
        "tags": [
          "AI agent"
        ],
        "summary": "Send an AI agent's drafted reply",
        "description": "Sends the drafted reply to the customer from the agent's connected inbox, or body when given (an edited reply).\n\n- A draft that books an appointment, sent unchanged, books it.\n- Refused for try emails, emails with no contact or no inbox, and with 409 when someone already answered the thread from the inbox itself (the email is then marked handled).\n- An email already replied to answers replied and sends nothing.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email_id",
            "in": "path",
            "required": true,
            "description": "Email id (from the agent's emails).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The reply to send instead of the draft."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-agent-emails/{email_id}/dismiss": {
      "post": {
        "operationId": "dismiss_ai_agent_email",
        "tags": [
          "AI agent"
        ],
        "summary": "Dismiss an AI agent's email",
        "description": "Marks the email handled without a reply.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email_id",
            "in": "path",
            "required": true,
            "description": "Email id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-agent-emails/{email_id}/retry": {
      "post": {
        "operationId": "retry_ai_agent_email",
        "tags": [
          "AI agent"
        ],
        "summary": "Retry a failed AI agent email",
        "description": "Runs a failed email again (only status failed). The agent sorts it and drafts a reply; in auto mode, with the agent on, it answers the customer straight away.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email_id",
            "in": "path",
            "required": true,
            "description": "Email id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/merge": {
      "post": {
        "operationId": "merge_leads",
        "tags": [
          "CRM leads"
        ],
        "summary": "Merge duplicate leads into one (cannot be undone)",
        "description": "The Leads page's Merge: the leads in `merge_ids` are merged into `keep_id` and then deleted for good, so confirm: true is required.\n\n- Blank fields on the kept lead (`full_name`, email, phone, notes, source, `utm_source`, `utm_medium`, `utm_campaign`, `assigned_to`, gclid, gbraid, wbraid) are filled from the merged leads, oldest first; a field the kept lead already has is never changed, and a merged lead's own phone or email is not kept as a second one (add it to the kept lead's `extra_phones` yourself if it matters).\n- The merged leads' tags go onto the kept lead, and their timeline (notes, texts, emails, calls), appointments, estimates, invoices, deals in extra pipelines, form submissions, website visits and queued follow-ups are re-pointed at it.\n- Nothing is sent to anyone and no stage changes.\n- It all happens together or not at all.\n- The answer lists the fields filled (`filled`; `fill_refused` true when the fill could not be saved, which happens when a merged lead's phone would have been copied: check the kept lead then), how many rows moved per kind (`moved`) and any kind that could not be moved (`not_moved`).\n- Every id must be a lead of this sub-account: any other id answers 404 with the ids in `details.not_found` and nothing is touched.\n- Up to 20 leads merged in a call.\n- Needs an admin key, like deleting leads.\n\nWho can call it: Owners and admins of the sub-account.\n\nRequired scope: `leads:admin`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "keep_id": {
                    "type": "string",
                    "description": "The lead to keep."
                  },
                  "merge_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1-20 lead ids to merge into keep_id. They are deleted."
                  },
                  "confirm": {
                    "type": "boolean",
                    "description": "Must be true."
                  }
                },
                "required": [
                  "workspace_id",
                  "keep_id",
                  "merge_ids",
                  "confirm"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "keep_id": "uuid",
                "merge_ids": [
                  "uuid",
                  "uuid"
                ],
                "confirm": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "keep_id": "uuid",
                    "merged": 2,
                    "merged_ids": [
                      "uuid",
                      "uuid"
                    ],
                    "filled": [
                      "email",
                      "notes"
                    ],
                    "fill_refused": false,
                    "moved": {
                      "lead_events": 14,
                      "lead_bookings": 1
                    },
                    "not_moved": [],
                    "note": "Merged. The merged leads are deleted; their history is on the kept lead. Nothing was sent to anyone."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-campaigns/{campaign_id}/start": {
      "post": {
        "operationId": "start_call_campaign",
        "tags": [
          "Calls"
        ],
        "summary": "Start or resume an AI calling campaign (places real calls)",
        "description": "Starts a draft, resumes a paused campaign, or runs a finished one again with a fresh run window: everyone who matches its audience now is put in line and called inside its calling hours.\n\n> **Warning:** Places real phone calls to real people and spends credits, so confirm: true is required; an assistant must tell the person which campaign and how many leads it would call (`audience_now` on `GET /v1/call-campaigns/{campaign_id}`) and get a clear yes first.\n\n- Refused (409) when the sub-account has no phone line that can place calls or the campaign is already running, (402) when it is out of credits.\n- `POST /v1/call-campaigns/{campaign_id}/pause` stops it.\n- Answers the campaign's status, run window and `leads_total`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "boolean",
                    "description": "Must be true: real calls will be placed and credits spent."
                  }
                },
                "required": [
                  "confirm"
                ],
                "additionalProperties": true
              },
              "example": {
                "confirm": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "campaign": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Spring follow-up",
                      "status": "running",
                      "paused_reason": null,
                      "start_at": "2026-11-16T15:00:00Z",
                      "ends_at": "2026-12-16T15:00:00Z",
                      "leads_total": 42
                    },
                    "note": "Running: its leads are called inside its calling hours. POST /v1/call-campaigns/{id}/pause stops it."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-campaigns/{campaign_id}/recall": {
      "post": {
        "operationId": "recall_call_campaign",
        "tags": [
          "Calls"
        ],
        "summary": "Call a campaign's leads again (places real calls)",
        "description": "The campaign's \"Call them again\".\n\n> **Warning:** Leads are called when the campaign is running or start is true, so confirm: true is required and an assistant must get a clear yes from the person first.\n\n- Puts leads back in line: new audience matches are added and finished leads with tries left are queued again.\n- Leads who asked not to be called, said not interested, were paused by the team, have a bad number or are won, lost or booked are never queued (blocked); only a hand-off to a person is lifted (unpaused).\n- Leads that already had every try stay finished (`at_limit`) unless fresh: true gives them the full number of tries again.\n- The campaign's status only changes with start: true (a draft, a finished campaign or one paused by a person then starts, with the same checks as start).\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "boolean",
                    "description": "Must be true: leads are put back in line to be called."
                  },
                  "start": {
                    "type": "boolean",
                    "description": "Also start the campaign so they are called. Default false."
                  },
                  "fresh": {
                    "type": "boolean",
                    "description": "Start from scratch: finished leads get the full number of tries again. Default false."
                  }
                },
                "required": [
                  "confirm"
                ],
                "additionalProperties": true
              },
              "example": {
                "confirm": true,
                "start": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "campaign": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Spring follow-up",
                      "status": "completed",
                      "paused_reason": null,
                      "start_at": "2026-10-01T15:00:00Z",
                      "ends_at": "2026-10-31T15:00:00Z",
                      "leads_total": 42
                    },
                    "queued": 12,
                    "unpaused": 2,
                    "at_limit": 20,
                    "blocked": 3,
                    "started": false,
                    "note": "The leads are in line; nobody is called until the campaign runs (POST /v1/call-campaigns/{id}/start, or recall with start: true)."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/invoices/{invoice_id}/payment-link": {
      "post": {
        "operationId": "create_invoice_payment_link",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Make an invoice's card payment page",
        "description": "Sets up card payment for the invoice on the business's own connected payment processor (Settings > Integrations) and answers `payment_url`.\n\n- Made for the invoice as it is now; an earlier unpaid page for the same invoice is cancelled, so it can't be paid twice.\n- With `authorize_net` and whop the customer pays from the invoice's own page (`pays_on_invoice_page` true; the page opens once the invoice is sent).\n- gateway left out: the processor the invoice already uses, else the sub-account's default, else whichever is connected with card payments on invoices switched on.\n- Nothing is charged by this call.\n- 409 when the invoice is paid or cancelled, has no customer email, card payment is off for it, its total is under the processor's minimum, or no processor is ready.\n- Never answers a key or the processor's own ids.\n\nWho can call it: Owners and admins.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoice id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "gateway": {
                    "type": "string",
                    "description": "Which connected processor. Default: the invoice's, else the sub-account's default.",
                    "enum": [
                      "stripe",
                      "authorize_net",
                      "whop"
                    ]
                  }
                },
                "additionalProperties": true
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "invoice_id": "uuid",
                    "gateway": "stripe",
                    "payment_url": "https://invoice.stripe.com/i/acct_x/live_y",
                    "pays_on_invoice_page": false,
                    "payment_status": "open",
                    "paid": false,
                    "note": "Made for the invoice as it is now; an earlier unpaid page for it was cancelled. POST /v1/invoices/{id}/send texts or emails the invoice with this page."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lead-feedback/datasets": {
      "get": {
        "operationId": "list_lead_feedback_datasets",
        "tags": [
          "Meta"
        ],
        "summary": "Lead quality feedback: the datasets to choose from",
        "description": "The Meta datasets on the sub-account's ad accounts, CRM ones first: id, name, `is_crm` (false = a website pixel), `last_event_at`, `made_by_ad_account`.\n\n- `ad_accounts` carry `own_dataset_id` and `can_create` (Meta lets an ad account make one dataset this way; with one there, connect it instead).\n- `saved_dataset_id` is the one lead stages go to now.\n- `suggested_dataset_id` is set only when nothing is saved and there is exactly one CRM dataset; a website pixel is never suggested.\n- problem says what stands in the way (Facebook not connected, no ad account picked).\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "saved_dataset_id": null,
                    "problem": null,
                    "ad_accounts": [
                      {
                        "id": "act_123456789",
                        "name": "Castillo Roofing",
                        "business_name": "Castillo Roofing LLC",
                        "own_dataset_id": null,
                        "can_create": true
                      }
                    ],
                    "datasets": [
                      {
                        "id": "1234567890123456",
                        "name": "Castillo Roofing Pixel",
                        "is_crm": false,
                        "last_event_at": "2026-11-14T16:00:00+0000",
                        "made_by_ad_account": null
                      }
                    ],
                    "suggested_dataset_id": null,
                    "events_manager_url": "https://business.facebook.com/events_manager2/list?business_id=987654321"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_lead_feedback_dataset",
        "tags": [
          "Meta"
        ],
        "summary": "Lead quality feedback: make a CRM dataset and connect it",
        "description": "Makes a new dataset on one of the sub-account's ad accounts, saves it as where lead stages are sent, switches lead quality feedback on and sends Meta one event of each stage (Lead, QualifiedLead, Schedule, Purchase, DisqualifiedLead) for a made-up person, never a real lead, so they show in Events Manager.\n\n- Meta treats it as a CRM dataset only after one step the person does in Events Manager (`next_step`, `events_manager_url`).\n- 409 when that ad account already made its one dataset (`details.own_dataset_id`: connect it with `PUT /v1/lead-feedback/dataset`), when Meta refuses, or when another dataset is already saved and replace isn't true.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "Which of the sub-account's ad accounts, like act_123456789. Default: its first."
                  },
                  "name": {
                    "type": "string",
                    "description": "The dataset's name in Meta, up to 60 characters. Default: \"<business> CRM\"."
                  },
                  "replace": {
                    "type": "boolean",
                    "description": "Change the dataset that is already saved. Default false."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Castillo Roofing CRM"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "dataset_id": "1234567890123456",
                    "name": "Castillo Roofing CRM",
                    "ad_account_id": "act_123456789",
                    "is_crm": false,
                    "events_received": 5,
                    "events_error": null,
                    "events_manager_url": "https://business.facebook.com/events_manager2/list/pixel/1234567890123456/overview?business_id=987654321",
                    "next_step": "Meta treats it as a CRM dataset only after one step in Events Manager: open the dataset > Set up Conversions API for CRM > Connect manually > Next. Read is_crm again afterwards."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/lead-feedback/dataset": {
      "put": {
        "operationId": "set_lead_feedback_dataset",
        "tags": [
          "Meta"
        ],
        "summary": "Lead quality feedback: connect a dataset",
        "description": "Saves a dataset the ad account already has (`GET /v1/lead-feedback/datasets`, or an id copied from Meta's Events Manager) as where lead stages are sent, switches lead quality feedback on and, unless `send_events` is false, sends one event of each stage for a made-up person.\n\n- Answers `is_crm` (null for an id the connected logins can't list) and, for a website pixel, the step in Events Manager that makes it a CRM dataset.\n- Pick a CRM dataset where there is one; never choose a website pixel for someone without asking.\n- 409 when another dataset is already saved and replace isn't true.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "dataset_id": {
                    "type": "string",
                    "description": "The dataset's id: 6 to 20 digits."
                  },
                  "send_events": {
                    "type": "boolean",
                    "description": "Send the setup events. Default true."
                  },
                  "replace": {
                    "type": "boolean",
                    "description": "Change the dataset that is already saved. Default false."
                  }
                },
                "required": [
                  "workspace_id",
                  "dataset_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "dataset_id": "1234567890123456"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "dataset_id": "1234567890123456",
                    "name": "Castillo Roofing CRM",
                    "is_crm": true,
                    "events_received": 5,
                    "events_error": null,
                    "events_manager_url": "https://business.facebook.com/events_manager2/list/pixel/1234567890123456/overview?business_id=987654321",
                    "next_step": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/forms": {
      "get": {
        "operationId": "list_smart_page_forms",
        "tags": [
          "Smart pages"
        ],
        "summary": "List a Smart Page's lead forms",
        "description": "The forms on one document of the page (path, default / for the home page): `form_id`, name, connected (submissions reach the CRM as leads), fields (the names a visitor fills in) and what happens after it's sent: mode message (title, message, `cta_label`, `cta_href`; all null = the page's own thank-you card) or redirect. A document built before element ids existed gets them stamped on its draft first (attributes only, no new version), as the builder does when it opens, so every form and element can be addressed.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "path",
            "in": "query",
            "required": false,
            "description": "Which document, e.g. /contact (default /).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "page_id": "uuid",
                    "path": "/",
                    "forms": [
                      {
                        "form_id": "form-1",
                        "name": "Free estimate",
                        "connected": true,
                        "fields": [
                          "name",
                          "phone",
                          "email"
                        ],
                        "mode": "message",
                        "title": "Thanks!",
                        "message": "We'll call you today.",
                        "cta_label": null,
                        "cta_href": null,
                        "redirect": null
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_smart_page_form",
        "tags": [
          "Smart pages"
        ],
        "summary": "Set what a Smart Page form does after it's sent",
        "description": "mode message: a thank-you card with title (up to 120 characters), message (up to 600) and an optional button (`cta_label` up to 60, `cta_href`: a page in the project like /book, or an https:// link); leave them all out to go back to the page's own card.\n\n- mode redirect: send the visitor to a page in this project (redirect, like /thank-you); never another site.\n- Saved to the draft as a free version (no AI, no credits); `POST /v1/smart-pages/{page_id}/publish` puts it live.\n- 409 when the form is no longer on the page.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "Which document (default /)."
                  },
                  "form_id": {
                    "type": "string",
                    "description": "The form (form_id from GET .../forms)."
                  },
                  "mode": {
                    "type": "string",
                    "description": "What happens after it's sent.",
                    "enum": [
                      "message",
                      "redirect"
                    ]
                  },
                  "title": {
                    "type": "string",
                    "description": "message: the card's title."
                  },
                  "message": {
                    "type": "string",
                    "description": "message: the card's words."
                  },
                  "cta_label": {
                    "type": "string",
                    "description": "message: a button on the card."
                  },
                  "cta_href": {
                    "type": "string",
                    "description": "message: where the button goes (/page or https://...)."
                  },
                  "redirect": {
                    "type": "string",
                    "description": "redirect: the page to send visitors to, like /thank-you."
                  }
                },
                "required": [
                  "form_id",
                  "mode"
                ],
                "additionalProperties": true
              },
              "example": {
                "form_id": "form-1",
                "mode": "message",
                "title": "Thanks!",
                "message": "We'll call you within the hour.",
                "cta_label": "Book a time now",
                "cta_href": "/book"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "page_id": "uuid",
                    "path": "/",
                    "version_no": 12,
                    "version_id": "uuid",
                    "changed": [
                      "form-1"
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/text-edits": {
      "post": {
        "operationId": "edit_smart_page_text",
        "tags": [
          "Smart pages"
        ],
        "summary": "Retype text on a Smart Page",
        "description": "The builder's inline edit: replaces the text of up to 100 elements by id in one free version (no AI, no credits).\n\n- Each edit takes `element_id` (the element's data-zu-id in the page's HTML: `GET /v1/smart-pages/{page_id}?include=html`) and text (plain words) or html (words with inline markup such as <strong> or <br>; scripts, styles, forms, embeds and event handlers are refused).\n- All or nothing: 409 when an element is no longer on the page.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "Which document (default /)."
                  },
                  "edits": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1-100: [{ element_id, text | html, label? }]. label names the element in the version list."
                  }
                },
                "required": [
                  "edits"
                ],
                "additionalProperties": true
              },
              "example": {
                "edits": [
                  {
                    "element_id": "hero-headline",
                    "text": "New roofs in 2 days"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "page_id": "uuid",
                    "path": "/",
                    "version_no": 13,
                    "version_id": "uuid",
                    "changed": [
                      "hero-headline"
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/style-edits": {
      "post": {
        "operationId": "edit_smart_page_style",
        "tags": [
          "Smart pages"
        ],
        "summary": "Style or remove one element of a Smart Page",
        "description": "The builder's Style panel on one element: styles sets any of color, background-color (hex, rgb(), hsl(), transparent), font-size, padding, border-radius (px, rem, em or %), font-weight (100-900, normal, bold), text-align (left, center, right, justify); \"\" puts the page's own style back.\n\n- Or remove: true takes the element off the page.\n- One free version (no AI, no credits).\n- 409 when a value isn't valid or the element is gone.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "Which document (default /)."
                  },
                  "element_id": {
                    "type": "string",
                    "description": "The element's data-zu-id."
                  },
                  "styles": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Property -> value, e.g. { \"color\": \"#1d4ed8\" }."
                  },
                  "remove": {
                    "type": "boolean",
                    "description": "Remove the element instead."
                  },
                  "label": {
                    "type": "string",
                    "description": "What to call the element in the version list."
                  }
                },
                "required": [
                  "element_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "element_id": "hero-button",
                "styles": {
                  "background-color": "#1d4ed8",
                  "border-radius": "12px"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "page_id": "uuid",
                    "path": "/",
                    "version_no": 14,
                    "version_id": "uuid",
                    "changed": [
                      "hero-button"
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/meta-lead-forms/available-pages": {
      "get": {
        "operationId": "list_meta_available_pages",
        "tags": [
          "Meta"
        ],
        "summary": "List the Facebook Pages that can be connected",
        "description": "The Facebook Pages the connected Facebook login can connect to this sub-account: what the Page picker in Settings > Leads shows (the caller's own Facebook login, plus the Pages of the agency owner's).\n\n- Each has `page_id` (what `POST /v1/meta-lead-forms/pages` takes), name, followers, `has_instagram`, `shared_by` (set when the Page comes from the agency owner's login), connected and id (this sub-account's connection, once connected).\n- The list is the one saved when the Pages were last read; refresh=true starts reading them from Facebook again in the background and answers the saved list with refreshing true, so ask again in a minute.\n- 409 `not_connected` when no Facebook login is connected, `login_expired` when it has run out, `missing_permission` when the login didn't allow Pages to be read.\n- The agency's owner and admins only, as connecting a Page.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refresh",
            "in": "query",
            "required": false,
            "description": "Read the Pages from Facebook again (in the background). Default false.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/meta-lead-forms/pages/{id}/forms": {
      "get": {
        "operationId": "list_meta_page_forms",
        "tags": [
          "Meta"
        ],
        "summary": "List a connected Page's Lead Forms with their questions",
        "description": "A connected Page's active Lead Forms, read from Meta now, newest first: so a form made after the Page was connected is listed too.\n\n- Each has `form_id`, name, `created_at`, connected (only a connected form makes leads), questions (key, label, type, field: the lead field its answer is saved to or null, `suggested_field`: what the app's mapper would pick), mapping (everything saved for the form), `phone_number_id` (the business number that texts its leads; null = the sub-account's default), `calendar_id` (the calendar they book on; null = automatic), `imessage_line_id` (set in the app) and `held_leads` (leads waiting because the form isn't connected).\n- `lead_fields` lists what a question can be mapped to: the core lead fields and the sub-account's custom fields as custom:<field key>.\n- 409 `not_connected` / `login_expired` / `facebook_refused` when Facebook can't be read with the connected login.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connected Page's id (from GET /v1/meta-lead-forms; not Facebook's page_id).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_meta_lead_form",
        "tags": [
          "Meta"
        ],
        "summary": "Set one Lead Form's mapping, phone number, calendar and switch",
        "description": "Changes what is saved for one Lead Form of a connected Page, as the form's editor in Settings > Leads does.\n\n- mapping is the form's whole mapping, question key -> lead field (`full_name`, `first_name`, `last_name`, email, phone, address, city, state, zip, inquiry, or custom:<field key> for one of the sub-account's custom fields; null leaves a question unmapped): every key must be a question the form asks now (`GET /v1/meta-lead-forms/pages/{id}/forms`) or one already saved for it.\n- `phone_number_id` is the business number that texts this form's leads and `calendar_id` the calendar they book on; both must be this sub-account's own, null goes back to the default.\n- connected turns the form on or off (only a connected form makes leads; from then on its new leads arrive like any live lead).\n- What isn't sent stays as it is; a form saved for the first time starts connected unless connected false is sent.\n- A form made after the Page was connected can be named: it is looked up on Facebook first.\n- The iMessage line a form texts from is set in the app.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The connected Page's id (from GET /v1/meta-lead-forms; not Facebook's page_id).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "form_id": {
                    "type": "string",
                    "description": "The Lead Form's id (digits)."
                  },
                  "mapping": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ question key: lead field | null }: the form's whole mapping."
                  },
                  "phone_number_id": {
                    "type": "string",
                    "description": "One of the sub-account's phone numbers (GET /v1/phone-numbers), or null for its default."
                  },
                  "calendar_id": {
                    "type": "string",
                    "description": "One of the sub-account's active calendars (GET /v1/calendars), or null for automatic."
                  },
                  "connected": {
                    "type": "boolean",
                    "description": "Whether the form makes leads."
                  },
                  "name": {
                    "type": "string",
                    "description": "The name shown for the form, up to 200 characters."
                  }
                },
                "required": [
                  "form_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "form_id": "9000000002",
                "mapping": {
                  "full_name": "full_name",
                  "phone_number": "phone",
                  "what_service": "custom:service"
                },
                "calendar_id": null,
                "connected": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/domains/{domain_id}/verify": {
      "post": {
        "operationId": "verify_smart_form_domain",
        "tags": [
          "Smart forms"
        ],
        "summary": "Check a domain's DNS record now",
        "description": "The app's Check: looks up where the hostname points right now. When it points here the domain becomes verified and its secure certificate is issued within minutes (live true once it is ready; forms and pages open on it from then).\n\n- The answer is the domain (verified, live, `ssl_status`, problem: what the check found in plain words, dns: the record to create) plus `points_to` (the end of its CNAME chain), addresses (its A records) and `edge_addresses` (the addresses a root domain's A records may use).\n- DNS changes often take 5 to 30 minutes: check again later rather than in a loop; pending domains are also re-checked on a timer.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "description": "The domain's id (from GET or POST /v1/smart-forms/domains).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-forms/domains/{domain_id}": {
      "delete": {
        "operationId": "delete_smart_form_domain",
        "tags": [
          "Smart forms"
        ],
        "summary": "Remove a domain",
        "description": "Removes the domain from the sub-account. Smart Pages on it go back to their shared link, forms stop opening on it, and a CRM address that used it goes back to the agency's. The DNS record at the provider is the business's to delete.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "description": "The domain's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{id}/domain": {
      "patch": {
        "operationId": "set_smart_page_domain",
        "tags": [
          "Smart pages"
        ],
        "summary": "Put a Smart Page on its own domain, or back on its shared link",
        "description": "Sets which of the sub-account's own domains opens this Smart Page (the builder's Address & domain): `domain_id` must be a verified domain of the same sub-account (`GET /v1/smart-forms/domains`; 409 `domain_not_verified` otherwise), or null for the shared link.\n\n- A domain opens one Smart Page: when another page has it the call is refused with 409 `domain_in_use` and that page's id, unless move true is sent, which moves the domain here and puts the other page back on its shared link (`moved_from`).\n- The answer has `public_url` (where the page opens now) and `shared_url` (which keeps working either way).\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The Smart Page's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain_id": {
                    "type": "string",
                    "description": "A verified domain's id, or null for the shared link."
                  },
                  "move": {
                    "type": "boolean",
                    "description": "Take the domain from the page that has it now. Default false."
                  }
                },
                "required": [
                  "domain_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "domain_id": "DOMAIN_ID"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments": {
      "get": {
        "operationId": "list_ad_comments",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Comments on a sub-account's ads",
        "description": "The comments people left on the sub-account's Facebook and Instagram ads (Ad Insights > Comments), newest first.\n\n- Each has its status (open = waiting on the business, replied, hidden, removed, done = set aside), what the AI made of it (category, reason, `suggested_reply`, `wants_hidden`), the reply that went out, anything waiting to go out, and the ad it is on.\n- Read on with before = `next_before`.\n- Anyone who works in the sub-account; the client's people get 403 while the agency manages the ads for them.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only these, comma separated: open, replied, hidden, removed, done.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Only these, comma separated: question, interest, praise, complaint, spam, abuse, tag, other.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "facebook or instagram.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "needs_review",
            "in": "query",
            "required": false,
            "description": "true: only comments the AI wants hidden that nobody has decided on.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Read on from here: the last answer's next_before.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-200 (default 50).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "comments": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "platform": "facebook",
                        "is_reply": false,
                        "author_name": "Dana P.",
                        "message": "Do you service Round Rock?",
                        "commented_at": "2026-11-16T18:02:11Z",
                        "likes": 1,
                        "status": "open",
                        "category": "question",
                        "ai": {
                          "reason": "Asks about the service area",
                          "suggested_reply": "We do! Send us a message and we'll get you on the schedule.",
                          "wants_hidden": false
                        },
                        "reply": null,
                        "hidden": null,
                        "waiting": null,
                        "error": null,
                        "ad": {
                          "platform": "facebook",
                          "ad_ids": [
                            "120210000000000001"
                          ],
                          "ad_name": "Roof inspection - video",
                          "campaign_name": "Leads - Austin",
                          "link": "https://www.facebook.com/...",
                          "image_url": null,
                          "comments": 14
                        }
                      }
                    ],
                    "has_more": false,
                    "next_before": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/status": {
      "get": {
        "operationId": "get_ad_comments_status",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Ad comments: what is connected and what the AI does",
        "description": "Which Facebook Pages and Instagram accounts the comments are read from (and whether each is connected), the AI settings, how many replies or hides are waiting to go out, when comments were last read, and paused when Meta asked to slow down (nothing automatic runs until then).\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "ad_insights_on": true,
                    "ad_accounts": 1,
                    "can_change_settings": true,
                    "pages": [
                      {
                        "id": "1029384756",
                        "name": "Acme Roofing",
                        "instagram": "acmeroofing",
                        "connected": true,
                        "problem": null,
                        "live_comments": true,
                        "live_instagram_comments": true
                      }
                    ],
                    "paused": null,
                    "last_read_at": "2026-11-17T12:00:00Z",
                    "last_read_problem": null,
                    "waiting_to_go_out": 0,
                    "ai_reads_today": 12,
                    "settings": {
                      "reply_mode": "suggest",
                      "reply_categories": [
                        "question",
                        "interest",
                        "praise"
                      ],
                      "hide_mode": "review",
                      "hide_categories": [
                        "spam",
                        "abuse"
                      ],
                      "hide_action": "hide",
                      "blocked_words": [],
                      "tone": "friendly",
                      "instructions": "",
                      "cta": ""
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/settings": {
      "put": {
        "operationId": "set_ad_comments_settings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Ad comments: set what the AI does by itself",
        "description": "Turning a mode off drops what it had waiting. Answers the same view as the status route.\n\nChanges only the settings you send:\n- `reply_mode` (off, suggest = the AI drafts and a person sends, auto = the AI replies)\n- `reply_categories` (question, interest, praise, complaint, other)\n- `hide_mode` (off, review = marked for a person, auto)\n- `hide_categories` (spam, abuse, complaint)\n- `hide_action` (hide or delete)\n- `blocked_words`\n- tone (friendly, professional, playful, short)\n- instructions and cta\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "settings": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The fields to change (they can also be sent at the top level)."
                  }
                },
                "required": [
                  "workspace_id",
                  "settings"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "settings": {
                  "reply_mode": "suggest",
                  "hide_mode": "review"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/sync": {
      "post": {
        "operationId": "sync_ad_comments",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Read new ad comments now",
        "description": "Reads the newest comments from Meta now instead of waiting for the next automatic read (there is a short cooldown and a daily cap, to stay inside Meta's limits). The AI then reads what is new in the background; list them a little later.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/bulk": {
      "post": {
        "operationId": "bulk_ad_comments",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Act on several ad comments at once",
        "description": "For up to 50 open comments: approve (send each one's AI draft as the Page's reply), hide, delete (confirm: true; cannot be undone), done (set aside) or keep (the AI wanted them hidden; keep them).\n\n- Replies, hides and deletes go out spaced apart, never together, to keep the Page safe: the answer says how many are waiting and about how long it takes.\n- Refused with 409 while Meta has asked to slow down.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "action": {
                    "type": "string",
                    "description": "approve, hide, delete, done or keep."
                  },
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 50 comment ids."
                  },
                  "confirm": {
                    "type": "boolean",
                    "description": "delete: must be true."
                  }
                },
                "required": [
                  "workspace_id",
                  "action",
                  "ids"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "action": "approve",
                "ids": [
                  "uuid"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "action": "approve",
                    "waiting_to_go_out": 1,
                    "done_in_about_minutes": 1
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/reply": {
      "post": {
        "operationId": "reply_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Reply to an ad comment",
        "description": "Posts a reply under the comment as the Page, right away. It is public: confirm the words with the person first. 409 for a hidden or removed comment (show it again first); 429 when Meta says slow down.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "The reply, up to 2,000 characters."
                  }
                },
                "required": [
                  "message"
                ],
                "additionalProperties": true
              },
              "example": {
                "message": "We do! Send us a message and we'll get you on the schedule."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/suggest": {
      "post": {
        "operationId": "suggest_ad_comment_reply",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Have the AI draft a reply to an ad comment",
        "description": "The AI writes (or rewrites) a reply from what it knows about the business; nothing is posted. The draft is kept on the comment as its `suggested_reply`. Uses the sub-account's daily AI allowance for comments (429 when it is used up).\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hint": {
                    "type": "string",
                    "description": "How to rewrite it: shorter, friendlier or formal."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/hide": {
      "post": {
        "operationId": "hide_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Hide an ad comment",
        "description": "Hides the comment on the ad (its author and their friends still see it). It can be shown again.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/unhide": {
      "post": {
        "operationId": "unhide_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Show a hidden ad comment again",
        "description": "Brings a hidden comment back on the ad. 409 when it isn't hidden.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/done": {
      "post": {
        "operationId": "done_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Set an ad comment aside",
        "description": "Marks the comment done without replying. Nothing is sent to Meta.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/reopen": {
      "post": {
        "operationId": "reopen_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Bring an ad comment back",
        "description": "Puts a comment that was set aside back to open. 409 for any other comment.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/keep": {
      "post": {
        "operationId": "keep_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Keep an ad comment the AI wanted hidden",
        "description": "Clears the AI's mark (and anything it had waiting for this comment). Nothing is sent to Meta.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}/cancel": {
      "post": {
        "operationId": "cancel_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Stop an ad comment's reply or hide that is waiting",
        "description": "Takes back a reply, hide or delete that is waiting to go out for this comment.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/comments/{comment_id}": {
      "delete": {
        "operationId": "delete_ad_comment",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Delete an ad comment",
        "description": "Removes the comment from the ad for good. It cannot be undone, so confirm=true is required; hiding can be undone.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "comment_id",
            "in": "path",
            "required": true,
            "description": "The comment's id, from GET /v1/ad-insights/comments.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "confirm",
            "in": "query",
            "required": true,
            "description": "Must be true.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/ads/{ad_id}/pause": {
      "post": {
        "operationId": "pause_ad",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Pause a Meta ad",
        "description": "Pauses one ad in the sub-account's Meta ad accounts (the ads `GET /v1/ad-insights` shows; `ad_id` is Meta's id).\n\n- Only an ad in an ad account attached to this sub-account, and shown on its dashboard, can be changed.\n- The agency's own people always can; the client's people only when the agency lets them pause ads (403 otherwise).\n- Kept in the sub-account's ad action log.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ad_id",
            "in": "path",
            "required": true,
            "description": "Meta's ad id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "Meta ad account id. Needed only when the sub-account has more than one."
                  },
                  "name": {
                    "type": "string",
                    "description": "The ad's name, for the action log."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "done": true,
                    "action": "pause_ad",
                    "id": "120210000000000001",
                    "status": "PAUSED"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/ads/{ad_id}/resume": {
      "post": {
        "operationId": "resume_ad",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Turn a Meta ad back on",
        "description": "Sets a paused ad to active, with the same rules as pausing. This spends ad money again: confirm with the person first.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ad_id",
            "in": "path",
            "required": true,
            "description": "Meta's ad id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "Meta ad account id. Needed only when the sub-account has more than one."
                  },
                  "name": {
                    "type": "string",
                    "description": "The ad's name, for the action log."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/campaigns/{campaign_id}/pause": {
      "post": {
        "operationId": "pause_ad_campaign",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Pause a Meta campaign",
        "description": "Pauses a campaign in the sub-account's Meta ad accounts (`campaign_id` is Meta's id, from `GET /v1/ad-insights`).\n\n- Only a campaign in an attached ad account and shown on the sub-account's dashboard.\n- The client's people need the agency's switch for pausing campaigns (403 otherwise).\n- Kept in the ad action log.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Meta's campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "Meta ad account id. Needed only when the sub-account has more than one."
                  },
                  "name": {
                    "type": "string",
                    "description": "The campaign's name, for the action log."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/campaigns/{campaign_id}/resume": {
      "post": {
        "operationId": "resume_ad_campaign",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Turn a Meta campaign back on",
        "description": "Sets a paused campaign to active, with the same rules as pausing. This spends ad money again: confirm with the person first.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Meta's campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "Meta ad account id. Needed only when the sub-account has more than one."
                  },
                  "name": {
                    "type": "string",
                    "description": "The campaign's name, for the action log."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/campaigns/{campaign_id}/budget": {
      "put": {
        "operationId": "set_ad_campaign_budget",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change a Meta campaign's budget",
        "description": "Sets the daily (default) or lifetime budget of a campaign, or of the ad set that holds the budget (send its id as `campaign_id`).\n\n- amount is in the ad account's currency: 25 means $25.00.\n- The client's people need the agency's switch for adjusting budgets, and stay inside the daily range the agency set (400 with the range otherwise).\n- Raising a budget spends more ad money: confirm with the person first.\n- Kept in the ad action log.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Meta's id of the campaign or ad set.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "amount": {
                    "type": "number",
                    "description": "The new budget in the ad account's currency (up to 100,000)."
                  },
                  "type": {
                    "type": "string",
                    "description": "daily (default) or lifetime.",
                    "enum": [
                      "daily",
                      "lifetime"
                    ]
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "Meta ad account id. Needed only when the sub-account has more than one."
                  }
                },
                "required": [
                  "workspace_id",
                  "amount"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "amount": 40,
                "type": "daily"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "done": true,
                    "action": "update_budget",
                    "id": "120210000000000002",
                    "budget": {
                      "amount": 40,
                      "type": "daily"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages": {
      "get": {
        "operationId": "list_smart_pages",
        "tags": [
          "Smart pages"
        ],
        "summary": "List Smart Pages",
        "description": "The sub-account's Smart Pages: landing pages and small websites with lead capture, built by an AI builder and hosted on the business's own domain. Each has status (draft | published), live, `public_url`, views, leads, building (queued | running | `awaiting_approval` | null) and builder (the page in the app).\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "smart_pages": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Roof repair Dallas",
                        "slug": "roof-repair-dallas-k3x9a",
                        "status": "published",
                        "live": true,
                        "model": "claude-opus-5-5",
                        "seo_title": "Roof Repair in Dallas | Castillo Roofing",
                        "seo_description": null,
                        "favicon_url": null,
                        "og_image_url": null,
                        "published_at": "2026-11-14T16:00:00Z",
                        "queue_paused": false,
                        "public_url": "https://crm.example.com/p/roof-repair-dallas-k3x9a",
                        "views": 1840,
                        "leads": 96,
                        "building": null,
                        "builder": "/clients/uuid/landing-pages/uuid",
                        "created_at": "2026-11-10T15:00:00Z",
                        "updated_at": "2026-11-14T16:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Create a Smart Page",
        "description": "Makes a page.\n\n- With brief, the AI builder starts building it at once (usually 2-6 minutes; watch `GET /v1/smart-pages/{page_id}/builds`): write it like a brief for a designer: the business, the offer, who it's for, the sections wanted, the style and colors, the phone number, and what the form should ask.\n- Without brief the page is empty until `POST /v1/smart-pages/{page_id}/edit` or `PUT /v1/smart-pages/{page_id}/html`.\n- A build costs credits like in the app (charged to the account that pays for the sub-account, when the build finishes); 402 when it is out of credits.\n- model: claude-opus-5-5 (default, the design model) or glm-5.3-flash.\n- A new page is a draft: publish it when it's ready.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "The page's name (also starts its link)."
                  },
                  "brief": {
                    "type": "string",
                    "description": "What to build, 20-20,000 characters. Starts the AI builder."
                  },
                  "model": {
                    "type": "string",
                    "description": "claude-opus-5-5 or glm-5.3-flash.",
                    "enum": [
                      "claude-opus-5-5",
                      "glm-5.3-flash"
                    ]
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Roof repair Dallas",
                "brief": "A landing page for Castillo Roofing in Dallas, TX. Offer: free roof inspection after hail. For homeowners. Sections: hero with the offer and a short form (name, phone, address), why us, how it works in 3 steps, service area, FAQ. Navy and orange, bold and trustworthy. Phone (214) 555-0142."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}": {
      "get": {
        "operationId": "get_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Get a Smart Page",
        "description": "One page: its settings, link, numbers, built (false until a first build or html), `unpublished_changes`, documents (the home page \"/\" and every extra page or file such as /thank-you or /robots.txt, with sizes) and `latest_build`. include=html adds html `{ path, content }`: the draft of the home page, or of path.\n\nWho can call it: People who manage the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "html to include a document's draft.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "path",
            "in": "query",
            "required": false,
            "description": "With include=html: which document (default /).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Update a Smart Page's settings",
        "description": "name, slug (the end of its link: 3-60 lowercase letters, numbers and dashes; changing it changes a published page's address), `seo_title`, `seo_description`, `favicon_url` and `og_image_url` (https links; null clears).\n\n- What is on the page changes with `POST /v1/smart-pages/{page_id}/edit` or `PUT /v1/smart-pages/{page_id}/html`.\n- A custom domain is connected in the app.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name."
                  },
                  "slug": {
                    "type": "string",
                    "description": "The end of the page's link."
                  },
                  "seo_title": {
                    "type": "string",
                    "description": "Title for search results and link previews."
                  },
                  "seo_description": {
                    "type": "string",
                    "description": "Description for search results and link previews."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "seo_title": "Roof Repair in Dallas | Castillo Roofing",
                "seo_description": "Free hail inspection, same-week repairs."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Delete a Smart Page",
        "description": "Takes the page offline and removes it from the list, as Delete in the app does. Leads it brought in stay.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/edit": {
      "post": {
        "operationId": "edit_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Ask the AI builder to change a Smart Page",
        "description": "Sends the page's AI builder a request in plain words, as typing in the builder's chat does: content, design, new sections, extra pages (\"add a /thank-you page\"), forms, anything.\n\n- mode build (default) makes the change; plan writes a plan first and waits (the build's status is `awaiting_approval` and plan holds it: send `approve_build_id` with that build's id to build it); chat answers a question without changing the page.\n- path is the document the request is about (default /, the home page).\n- attachments are up to 4 https pictures to use or copy.\n- One build runs per page at a time: a request sent meanwhile waits in line (queued: true) and starts by itself.\n- Answers 202 with `build_id`; `GET /v1/smart-pages/{page_id}/builds` shows when it is done.\n- Costs credits like in the app; 402 when out of credits.\n- Nothing goes live until the page is published.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "What to change or build, up to 20,000 characters. Required unless approve_build_id is sent."
                  },
                  "mode": {
                    "type": "string",
                    "description": "build (default), plan or chat.",
                    "enum": [
                      "build",
                      "plan",
                      "chat"
                    ]
                  },
                  "path": {
                    "type": "string",
                    "description": "The document it's about (default /)."
                  },
                  "attachments": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 4 https picture links."
                  },
                  "approve_build_id": {
                    "type": "string",
                    "description": "Build a plan that is waiting for approval."
                  },
                  "model": {
                    "type": "string",
                    "description": "claude-opus-5-5 or glm-5.3-flash (default: the page's)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "prompt": "Make the hero headline 'Hail damage? Free roof inspection this week' and add a section with three customer reviews above the FAQ."
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "build_id": "uuid",
                    "queued": false,
                    "note": "The builder is working. GET /v1/smart-pages/{id}/builds shows when it is done (usually 1-5 minutes)."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/builds": {
      "get": {
        "operationId": "list_smart_page_builds",
        "tags": [
          "Smart pages"
        ],
        "summary": "List a Smart Page's builds",
        "description": "The last 15 builds (status queued | running | `awaiting_approval` | done | failed | canceled, stage while running, plan for a plan, error when it failed), the requests waiting in line, `queue_paused`, and the builder's last messages (what it said it changed, or its answer to a chat).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/cancel-build": {
      "post": {
        "operationId": "cancel_smart_page_build",
        "tags": [
          "Smart pages"
        ],
        "summary": "Cancel a Smart Page's build",
        "description": "Stops the build that is queued, running or waiting for approval. 409 when none is.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/html": {
      "put": {
        "operationId": "write_smart_page_html",
        "tags": [
          "Smart pages"
        ],
        "summary": "Write a Smart Page document yourself",
        "description": "Replaces one document's draft with html you wrote: the home page (path /, default) or an extra page or file (path /thank-you, /services/roofing, /robots.txt, /sitemap.xml; a path that doesn't exist yet is created, up to 60).\n\n- A page must be a whole document (<!doctype html> ... </body></html>), up to 1,500,000 characters.\n- To edit what's there, read it first with `GET /v1/smart-pages/{page_id}?include=html`.\n- Free.\n- Saved as a version (label names it in the builder's history), so Restore in the builder can undo it.\n- Refused (409) while a build is running on the page.\n- Lead forms on the page keep working when they keep the builder's own form markup.\n- Nothing goes live until the page is published.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "html": {
                    "type": "string",
                    "description": "The whole document."
                  },
                  "path": {
                    "type": "string",
                    "description": "Which document (default /)."
                  },
                  "label": {
                    "type": "string",
                    "description": "A name for this version in the builder's history."
                  }
                },
                "required": [
                  "html"
                ],
                "additionalProperties": true
              },
              "example": {
                "path": "/thank-you",
                "html": "<!doctype html><html><head><title>Thank you</title></head><body><h1>Thanks! We'll call you shortly.</h1></body></html>",
                "label": "New thank-you page"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/publish": {
      "post": {
        "operationId": "publish_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Publish a Smart Page",
        "description": "Puts the draft live at `public_url`, with every extra page. 409 when nothing has been built yet. Publishing again after a change updates the live page.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/smart-pages/{page_id}/unpublish": {
      "post": {
        "operationId": "unpublish_smart_page",
        "tags": [
          "Smart pages"
        ],
        "summary": "Unpublish a Smart Page",
        "description": "Takes the page offline. The draft and everything published before stay, so publishing again brings it back.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_id",
            "in": "path",
            "required": true,
            "description": "Page id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-texting": {
      "get": {
        "operationId": "get_ai_texting",
        "tags": [
          "AI agent"
        ],
        "summary": "Read the AI texting agent and automatic text settings",
        "description": "AI replies, agent name, reply mode, goal, what it knows, booking link, first text, send window, hand-off, confirmation and reminder texts, missed-call text-back, email greeting, and a preview of its prompt. Says whether the sub-account has a phone number.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "set_ai_texting",
        "tags": [
          "AI agent"
        ],
        "summary": "Change the AI texting agent and automatic texts",
        "description": "Changes how the AI texts a sub-account's leads. Send only the settings to change. Every value is checked.\n\nAI replies:\n- `ai_replies` turns them on or off. Turning them on lets the AI answer conversations still waiting for a reply.\n- `agent_name`, `reply_mode` (auto | suggest), goal (`book_appointment` | `collect_details` | `customer_support`), `business_context`, `booking_link`.\n- `max_replies` (1-15), `reply_delay_minutes` (1-120), `ai_can_cancel`, `ai_answers_email`.\n- `handoff_when_unsure`, `pause_ai_on_handoff`, `handoff_resume_days` (0, 1, 2, 3 or 7).\n- `prompt_addition` adds one more rule; prompt rewrites the whole instructions.\n\nThe first text to a new lead:\n- `greet_new_leads`, `first_message`, `greet_delay_minutes`, `form_greet_delay_minutes`.\n- `smart_first_text`: the AI writes each new lead's first text from their answers and the right calendar's open times; `first_message` becomes the backup.\n- `smart_first_text_goal`: what that text should get them to do. Empty means book an appointment.\n- `email_greeting`, `email_greeting_subject`, `email_greeting_body`.\n\nMissed calls, confirmations and reminders:\n- `missed_call_text`, `missed_call_message`.\n- `confirmation_text`, `confirmation_message`.\n- `confirmation_email` (the confirmation email with a calendar invite, plus the move and cancel emails), `confirmation_email_language` (en | es).\n- `reminder_24h`, `reminder_24h_message`, `reminder_1h`, `reminder_1h_message`.\n- `reminder_5m` (off by default), `reminder_5m_message`.\n\nWhen texts may go out:\n- `send_window` (anytime | daily | `booking_hours`), `send_window_start` and `send_window_end` (\"HH:MM\").\n\nWho can call it: Owners, agency admins and client admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ai_replies": {
                    "type": "boolean",
                    "description": "The AI answers leads by text."
                  },
                  "agent_name": {
                    "type": "string",
                    "description": "First name the AI texts as (max 40)."
                  },
                  "reply_mode": {
                    "type": "string",
                    "description": "suggest = drafts each reply for a teammate to approve (GET /v1/reply-suggestions).",
                    "enum": [
                      "auto",
                      "suggest"
                    ]
                  },
                  "first_message": {
                    "type": "string",
                    "description": "First text to a new lead. Variables {first_name}, {agent}, {business}, {service}."
                  },
                  "send_window": {
                    "type": "string",
                    "description": "When automated texts may go out.",
                    "enum": [
                      "anytime",
                      "daily",
                      "booking_hours"
                    ]
                  },
                  "prompt_addition": {
                    "type": "string",
                    "description": "A rule added to the end of the AI's prompt (max 2000)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "ai_replies": true,
                "agent_name": "Sarah",
                "reply_mode": "auto",
                "prompt_addition": "Always mention free estimates."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ai_texting": {
                      "ai_replies": true,
                      "agent_name": "Sarah",
                      "reply_mode": "auto",
                      "send_window": "daily",
                      "send_window_start": "08:00",
                      "send_window_end": "21:00",
                      "prompt_characters": 2140
                    },
                    "changed": [
                      "ai_replies",
                      "agent_name",
                      "reply_mode",
                      "prompt_addition"
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/nurture-sequence": {
      "get": {
        "operationId": "get_nurture",
        "tags": [
          "AI agent"
        ],
        "summary": "Read the automatic follow-up sequence",
        "description": "Every text and email step with the day it goes out, whether each channel is on, and offers whose own follow-ups replace it for the leads they match.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_nurture",
        "tags": [
          "AI agent"
        ],
        "summary": "Replace the follow-up texts (or emails)",
        "description": "Replaces one channel's steps and turns it on. Timing is the app's: the first 3 hours after the first text, then front-loaded days over `span_days` (about 5 days per message, at most 60), or the explicit days you send.\n\n- At most 40 texts or 60 emails; email needs a verified sending domain.\n- Pending sends that would change channel are cancelled.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "channel": {
                    "type": "string",
                    "description": "Default sms.",
                    "enum": [
                      "sms",
                      "email"
                    ]
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "One message per step, in order."
                  },
                  "subjects": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Email only: one subject per message."
                  },
                  "span_days": {
                    "type": "number",
                    "description": "Days from the first message to the last (1-365)."
                  },
                  "days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Instead of span_days: the day each message goes out, going up. 0 = 3 hours in."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "required": [
                  "workspace_id",
                  "messages"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "channel": "sms",
                "messages": [
                  "Hi {first_name}, still looking for a quote?",
                  "Quick check-in from {business}: want me to hold a time for you?"
                ],
                "span_days": 7
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_nurture",
        "tags": [
          "AI agent"
        ],
        "summary": "Switch follow-ups on or off, or reword one step",
        "description": "Send enabled, or step with message (and subject for email). A reworded step keeps its timing.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "channel": {
                    "type": "string",
                    "description": "Default sms.",
                    "enum": [
                      "sms",
                      "email"
                    ]
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "On or off."
                  },
                  "step": {
                    "type": "number",
                    "description": "Which step to reword (1 = first)."
                  },
                  "message": {
                    "type": "string",
                    "description": "The step's new wording."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Email only: the new subject."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "channel": "sms",
                "step": 2,
                "message": "Hi {first_name}, any questions I can answer?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "clear_nurture",
        "tags": [
          "AI agent"
        ],
        "summary": "Remove one channel's follow-up steps",
        "description": "Switches that channel off and cancels its pending sends.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "Default sms.",
            "schema": {
              "type": "string",
              "enum": [
                "sms",
                "email"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/business-profile": {
      "get": {
        "operationId": "get_business_profile",
        "tags": [
          "Setup"
        ],
        "summary": "Read the business profile",
        "description": "Name, industry, time zone, address, country, business phone and business email (Settings → General).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "set_business_profile",
        "tags": [
          "Setup"
        ],
        "summary": "Change the business profile",
        "description": "Send only what changes. A new time zone also moves the booking hours' time zone, as in the app.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Max 120."
                  },
                  "industry": {
                    "type": "string",
                    "description": "Max 80."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA zone, e.g. America/Chicago."
                  },
                  "address_line1": {
                    "type": "string",
                    "description": "Street."
                  },
                  "address_line2": {
                    "type": "string",
                    "description": "Suite, unit."
                  },
                  "city": {
                    "type": "string",
                    "description": "City."
                  },
                  "state": {
                    "type": "string",
                    "description": "State or region."
                  },
                  "postal_code": {
                    "type": "string",
                    "description": "ZIP or postal code."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country code (US, CA, GB, AU; \"United States\" works too), or null. It picks the State list on leads, forms and booking pages, and the list a lead's state is matched against when the lead has no phone."
                  },
                  "business_phone": {
                    "type": "string",
                    "description": "US 10-digit or + and a country code."
                  },
                  "business_email": {
                    "type": "string",
                    "description": "Email address."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "timezone": "America/Chicago",
                "country": "US",
                "business_phone": "+14155550123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/overview": {
      "get": {
        "operationId": "get_overview",
        "tags": [
          "Dashboard"
        ],
        "summary": "Dashboard numbers for a window",
        "description": "New leads, booked leads and appointments (each with the previous window of the same length for comparison), upcoming appointments, contacted, won and closed, speed to lead (median minutes to the first reply: anyone, AI or automation, a person), AI replies sent, calls (answered, missed, voicemails, AI calls, talk time), and `stage_reach`: of the leads created in the window, how many reached each pipeline stage (`total`, and `reached` keyed by stage key from `GET /v1/stages`; a lead counts for every stage it has been in, so a lead that sat and then won counts for both; the Overview's \"<Stage> rate\" cards divide reached by total).\n\n- Moves made before 2026-10-16 are not known.\n- `stage_reach` is null if it could not be read.\n- Viewers limited to their own leads see only those.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "1-365, default 30.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO start, instead of days (window at most 366 days).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO end, default now.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "window": {
                      "from": "2026-08-31T00:00:00Z",
                      "to": "2026-09-30T00:00:00Z",
                      "days": 30
                    },
                    "stats": {
                      "leads": 142,
                      "prev_leads": 120,
                      "booked_leads": 38,
                      "prev_booked_leads": 31,
                      "appointments": 41,
                      "upcoming_appointments": 12,
                      "contacted": 131,
                      "won": 9,
                      "closed": 15,
                      "new_unworked": 4,
                      "median_response_minutes": 0.8,
                      "median_response_minutes_auto": 0.4,
                      "median_response_minutes_human": 22.5,
                      "ai_replies": {
                        "total": 512,
                        "sms": 498,
                        "email": 9,
                        "other_channels": 5,
                        "leads": 96
                      },
                      "calls": {
                        "total": 88,
                        "inbound": 30,
                        "outbound": 58,
                        "answered": 61,
                        "missed_inbound": 6,
                        "voicemails": 9,
                        "ai_calls": 40,
                        "ai_receptionist_calls": 8,
                        "talk_seconds": 15540
                      },
                      "stage_reach": {
                        "total": 142,
                        "reached": {
                          "new": 142,
                          "contacted": 131,
                          "sat": 44,
                          "booked": 38,
                          "won": 9
                        }
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/health-score": {
      "get": {
        "operationId": "get_health_score",
        "tags": [
          "Dashboard"
        ],
        "summary": "A sub-account's health score",
        "description": "The 0-100 health score from the Sub-accounts list and its breakdown: grade (Excellent, Healthy, Needs attention, At risk, Dormant), the five factors (activity recency 15, lead flow 20, speed to lead 25, leads answered 15, booking rate 25) with the points each earned, its value and how it was worked out; a factor that can't be measured yet has earned null (listed in `not_measured`) and its weight is spread over the rest.\n\n- verdict says what goes well and what holds it back; actions is what would raise it, biggest gain first (gain in score points; path is the page inside the sub-account, e.g. settings?tab=messaging), with people waiting for a reply first.\n- history is the score at the end of each of the last weeks (oldest first, the last one now), and `last_30_days` the funnel, reply speed and lead sources behind it.\n- Leads leave out spam and imported lists.\n\nWho can call it: Any member; Technicians and Viewers limited to their own leads are scored on those.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "weeks",
            "in": "query",
            "required": false,
            "description": "Weeks of history, 1-26, default 12.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "name": "Bright Smiles Dental",
                    "score": 72,
                    "grade": "Healthy",
                    "is_new": false,
                    "verdict": "Active today and first replies within 42s. The booking rate (14%) is what holds it back.",
                    "factors": [
                      {
                        "key": "recency",
                        "label": "Activity recency",
                        "weight": 15,
                        "earned": 15,
                        "applies": true,
                        "value": "Today",
                        "detail": "Last new lead, message or call was less than a day ago.",
                        "hint": "Full points when something happens in the account every day.",
                        "gain": 0
                      },
                      {
                        "key": "booking",
                        "label": "Booking rate (30 days)",
                        "weight": 25,
                        "earned": 14,
                        "applies": true,
                        "value": "14%",
                        "detail": "6 of 42 leads from the last 30 days booked an appointment.",
                        "hint": "Full points at a 25% booking rate.",
                        "gain": 11
                      }
                    ],
                    "not_measured": [],
                    "applied_weight": 100,
                    "actions": [
                      {
                        "key": "follow_ups",
                        "title": "Turn on follow-ups",
                        "why": "Only 14% of leads booked. Most bookings come from the 2nd to 5th message.",
                        "gain": 11,
                        "path": "settings?tab=messaging&section=nurture",
                        "cta": "Follow-up settings",
                        "urgent": false
                      }
                    ],
                    "inputs": {
                      "last_activity_at": "2026-10-29T14:10:00Z",
                      "leads_7d": 9,
                      "bookings_7d": 2,
                      "leads_30d": 42,
                      "booked_30d": 6,
                      "median_response_seconds": 42,
                      "reply_base_30d": 41,
                      "replied_30d": 40
                    },
                    "waiting": {
                      "count": 0,
                      "longest_since": null
                    },
                    "history": [
                      {
                        "as_of": "2026-08-13T15:00:00Z",
                        "score": 64,
                        "grade": "Needs attention"
                      },
                      {
                        "as_of": "2026-10-29T15:00:00Z",
                        "score": 72,
                        "grade": "Healthy"
                      }
                    ],
                    "last_30_days": {
                      "funnel": {
                        "leads": 42,
                        "replied": 40,
                        "booked": 6,
                        "showed": 4,
                        "no_show": 1,
                        "won": 3,
                        "lost": 5,
                        "still_new": 1
                      },
                      "speed": {
                        "within_1m": 30,
                        "within_5m": 6,
                        "within_1h": 2,
                        "within_1d": 1,
                        "later": 0,
                        "no_reply": 1
                      },
                      "sources": [
                        {
                          "channel": "facebook",
                          "leads": 30,
                          "booked": 4
                        }
                      ],
                      "upcoming_appointments": 5
                    },
                    "setup": {
                      "phone_numbers": 1,
                      "ai_texter": true,
                      "first_text": true,
                      "follow_ups": false,
                      "calendars": 1,
                      "automations": 3,
                      "meta_pages": 1,
                      "smart_forms": 0,
                      "webhooks": 0
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/health-scores": {
      "get": {
        "operationId": "list_health_scores",
        "tags": [
          "Dashboard"
        ],
        "summary": "Health scores of every sub-account",
        "description": "Every sub-account the key's person can open, best first, scored as `GET /v1/health-score` scores them: score, grade, rank among the active ones (null for a sub-account where nothing has happened yet), the factor holding it back most (`held_back_by`, when it costs 3 points or more), each factor's points and the inputs; plus the median score and the medians of each input across the active ones.\n\n- A key restricted to one sub-account gets just that one.\n- Archived sub-accounts are left out unless `include_archived`=true.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": false,
            "description": "Just this sub-account.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_archived",
            "in": "query",
            "required": false,
            "description": "Also archived sub-accounts.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspaces": [
                      {
                        "workspace_id": "uuid",
                        "name": "Bright Smiles Dental",
                        "archived": false,
                        "score": 72,
                        "grade": "Healthy",
                        "is_new": false,
                        "rank": 3,
                        "held_back_by": {
                          "key": "booking",
                          "label": "Booking rate (30 days)",
                          "value": "14%",
                          "gain": 11
                        },
                        "factors": [
                          {
                            "key": "booking",
                            "earned": 14,
                            "weight": 25,
                            "value": "14%",
                            "gain": 11
                          }
                        ],
                        "inputs": {
                          "last_activity_at": "2026-10-29T14:10:00Z",
                          "leads_7d": 9,
                          "bookings_7d": 2,
                          "leads_30d": 42,
                          "booked_30d": 6,
                          "median_response_seconds": 42,
                          "reply_base_30d": 41,
                          "replied_30d": 40
                        }
                      }
                    ],
                    "active": 18,
                    "median_score": 61,
                    "medians": {
                      "leads_7d": 6,
                      "median_response_seconds": 95,
                      "answer_rate": 88,
                      "booking_rate": 17,
                      "days_since_activity": 0.4
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "operationId": "get_usage",
        "tags": [
          "Dashboard"
        ],
        "summary": "Credits used by tool",
        "description": "What the sub-account spent in a window, by tool (the Usage tab's names: texts, lead alert texts, email, AI text replies, website chat widget, AI agents, phone calls, AI receptionist, AI calling, phone numbers, ad tools) and by day. unpaid counts events that ran while the account was out of credits.\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "1-365, default 30.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO start, instead of days.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO end, default now.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "window": {
                      "from": "2026-08-31T00:00:00Z",
                      "to": "2026-09-30T00:00:00Z",
                      "days": 30
                    },
                    "total_credits": 318.5,
                    "total_events": 2210,
                    "unpaid_events": 0,
                    "by_tool": [
                      {
                        "tool": "ai_text",
                        "label": "AI text replies",
                        "events": 512,
                        "credits": 128,
                        "unpaid": 0
                      },
                      {
                        "tool": "messaging",
                        "label": "Texts",
                        "events": 1404,
                        "credits": 105.3,
                        "unpaid": 0
                      }
                    ],
                    "by_day": [
                      {
                        "date": "2026-09-29",
                        "events": 81,
                        "credits": 11.5
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/conversations": {
      "get": {
        "operationId": "list_conversations",
        "tags": [
          "Inbox"
        ],
        "summary": "The Inbox: conversations, newest first",
        "description": "Every lead with a message either way (or an unread one), like the Inbox: unread count, archive state, whether the AI is paused on it (and the question it handed to the team), and the last message or call.\n\n- The first page also returns the Inbox counts.\n- Read the thread with `GET /v1/leads/{lead_id}/conversation`.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "description": "true = the Archived tab. Default false.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "unread",
            "in": "query",
            "required": false,
            "description": "Only unread conversations.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "assigned_to",
            "in": "query",
            "required": false,
            "description": "A user id, \"me\" or \"unassigned\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Name, email or phone contains (2-80 characters).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "imessage_line_id",
            "in": "query",
            "required": false,
            "description": "Only the conversations this iMessage Mac has had (GET /v1/imessage/lines), like the Inbox's number filter.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "conversations": [
                      {
                        "lead_id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Jane Doe",
                        "phone": "+14155550123",
                        "email": null,
                        "status": "contacted",
                        "stage_key": "contacted",
                        "assigned_to": null,
                        "unread": true,
                        "unread_count": 2,
                        "archived": false,
                        "ai": {
                          "paused": false,
                          "paused_until": null,
                          "pause_reason": null,
                          "handoff_question": null
                        },
                        "channel": "sms",
                        "last_message": {
                          "id": "uuid",
                          "channel": "sms",
                          "direction": "inbound",
                          "body": "Can you come Thursday?",
                          "subject": null,
                          "sent_by": null,
                          "created_at": "2026-09-30T15:02:00Z"
                        },
                        "last_inbound_at": "2026-09-30T15:02:00Z",
                        "last_outbound_at": "2026-09-30T14:40:00Z",
                        "last_activity_at": "2026-09-30T15:02:00Z"
                      }
                    ],
                    "has_more": true,
                    "next_cursor": "MjAyNi0wOS0zMFQxNTowMjowMCswMDowMHx1dWlk",
                    "counts": {
                      "open": 210,
                      "unread": 7,
                      "archived": 54
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/conversations/{lead_id}/read": {
      "post": {
        "operationId": "mark_conversation_read",
        "tags": [
          "Inbox"
        ],
        "summary": "Mark a conversation read",
        "description": "Anyone who can see the lead can, as in the Inbox.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/conversations/{lead_id}/unread": {
      "post": {
        "operationId": "mark_conversation_unread",
        "tags": [
          "Inbox"
        ],
        "summary": "Mark a conversation unread",
        "description": "Required scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/conversations/{lead_id}/archive": {
      "post": {
        "operationId": "archive_conversation",
        "tags": [
          "Inbox"
        ],
        "summary": "Archive a conversation",
        "description": "As in the app, archiving switches the lead's automatic follow-up texts off. A new message from the lead brings the conversation back.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/conversations/{lead_id}/unarchive": {
      "post": {
        "operationId": "unarchive_conversation",
        "tags": [
          "Inbox"
        ],
        "summary": "Move a conversation back to the Inbox",
        "description": "Follow-ups switched off by archiving stay off.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/ai-pause": {
      "post": {
        "operationId": "set_lead_ai_pause",
        "tags": [
          "Inbox"
        ],
        "summary": "Pause or resume the AI on one lead",
        "description": "paused: true stops AI replies to this lead (and its automatic follow-ups at send time) until someone turns it back on, or until `until`. paused: false turns it back on and clears any hand-off. The sub-account-wide switch is `ai_replies` on `PATCH /v1/ai-texting`.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paused": {
                    "type": "boolean",
                    "description": "Pause (true) or resume (false)."
                  },
                  "until": {
                    "type": "string",
                    "description": "ISO time the AI turns itself back on (paused: true only, at most a year away)."
                  }
                },
                "required": [
                  "paused"
                ],
                "additionalProperties": true
              },
              "example": {
                "paused": true,
                "until": "2026-10-07T15:00:00Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead_id": "uuid",
                    "ai": {
                      "paused": true,
                      "paused_until": "2026-10-07T15:00:00.000Z",
                      "pause_reason": "Paused from the API",
                      "handoff_question": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reply-suggestions": {
      "get": {
        "operationId": "list_reply_suggestions",
        "tags": [
          "Inbox"
        ],
        "summary": "AI suggested replies waiting for a teammate",
        "description": "When AI texting's `reply_mode` is suggest, the AI drafts its reply to each text or email here instead of sending it.\n\n- Each one shows the lead, the draft, and the appointment it would book or cancel.\n- `reply_mode` in the response says whether the sub-account is in suggest mode.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Default pending.",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "sending",
                "sent",
                "dismissed",
                "superseded",
                "failed",
                "all"
              ]
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "One lead's suggestions.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "reply_mode": "suggest",
                    "suggestions": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "lead_id": "uuid",
                        "channel": "sms",
                        "body": "Thursday at 2pm works! I've put you down, see you then.",
                        "status": "pending",
                        "error": null,
                        "inbound_at": "2026-09-30T15:02:00Z",
                        "sent_body": null,
                        "decided_at": null,
                        "created_at": "2026-09-30T15:02:20Z",
                        "updated_at": "2026-09-30T15:02:20Z",
                        "books": {
                          "starts_at": "2026-10-02T19:00:00Z",
                          "ends_at": "2026-10-02T20:00:00Z",
                          "title": "Roof inspection",
                          "timezone": "America/New_York",
                          "location": null,
                          "is_arrival_window": false
                        },
                        "cancels": null,
                        "lead": {
                          "id": "uuid",
                          "full_name": "Jane Doe",
                          "phone": "+14155550123",
                          "email": null
                        }
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reply-suggestions/{suggestion_id}/dismiss": {
      "post": {
        "operationId": "dismiss_reply_suggestion",
        "tags": [
          "Inbox"
        ],
        "summary": "Dismiss a suggested reply",
        "description": "Nothing is sent. The AI does not suggest again until the lead writes. 409 when it was already handled.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "suggestion_id",
            "in": "path",
            "required": true,
            "description": "Suggestion id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reply-suggestions/{suggestion_id}/approve": {
      "post": {
        "operationId": "approve_reply_suggestion",
        "tags": [
          "Inbox"
        ],
        "summary": "Send a suggested reply",
        "description": "Sends it to the lead as the AI (edited, if you send body), makes the booking or cancellation it decided on, and is charged exactly like an automatic AI reply plus the text, through the same code as the Inbox's Send button. 409 = someone already answered or the lead wrote again (nothing sent), 422 = not sent for a reason in `error` (e.g. AI paused, out of credits, that time is no longer open), 503 = a sending hiccup, try again.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `messaging:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "suggestion_id",
            "in": "path",
            "required": true,
            "description": "Suggestion id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The edited reply to send instead (texts up to 1600 characters, emails 5000)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "body": "Thursday at 2pm works! See you then."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "suggestion_id": "uuid",
                    "sent": true,
                    "status": "sent",
                    "booked": true,
                    "cancelled": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/reply-ideas": {
      "post": {
        "operationId": "lead_reply_ideas",
        "tags": [
          "Inbox"
        ],
        "summary": "Reply ideas for a conversation",
        "description": "The Inbox composer's reply assistant: up to three ready replies in the business's tone (Settings > Reply assistant), written from the conversation, calls, appointments, the lead's stage and the AI Brain.\n\n- `kind` says what they are: reply (an answer to their message), `follow_up` (a nudge after the business's own message) or first (the first message).\n- Send `draft` to polish your own text instead (`how`: improve, grammar, shorter, a tone, or custom with `instruction`); the answer is `text`.\n- Nothing is sent or saved: send the one you pick with `POST /v1/messages`.\n- Free, and counted in the person's hourly allowance shared with the Inbox (429 when it's used up).\n- Anyone who can see the lead.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "description": "Where the reply goes. Default sms.",
                    "enum": [
                      "sms",
                      "email",
                      "chat",
                      "instagram",
                      "messenger"
                    ]
                  },
                  "tone": {
                    "type": "string",
                    "description": "New ideas only: this tone instead of the business's own.",
                    "enum": [
                      "friendly",
                      "professional",
                      "casual",
                      "formal"
                    ]
                  },
                  "avoid": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "New ideas only: up to 6 replies you already have, to get different ones."
                  },
                  "draft": {
                    "type": "string",
                    "description": "Polish this text instead (max 4000)."
                  },
                  "how": {
                    "type": "string",
                    "description": "With draft. Default improve.",
                    "enum": [
                      "improve",
                      "grammar",
                      "shorter",
                      "friendly",
                      "professional",
                      "casual",
                      "formal",
                      "custom"
                    ]
                  },
                  "instruction": {
                    "type": "string",
                    "description": "With how custom: what to change (max 300)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "channel": "sms"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead_id": "uuid",
                    "channel": "sms",
                    "kind": "reply",
                    "replies": [
                      {
                        "label": "Confirm Thursday",
                        "text": "Hi Jane, Thursday at 2 works. See you then!"
                      },
                      {
                        "label": "Offer a time",
                        "text": "Hi Jane, we can do Thursday at 2 or Friday morning. Which suits you?"
                      }
                    ],
                    "subject": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/needs-reply": {
      "get": {
        "operationId": "list_needs_reply",
        "tags": [
          "Inbox"
        ],
        "summary": "Who is waiting on a person (Needs you now)",
        "description": "The CRM overview's \"Needs you now\": everyone from the last 14 days waiting on someone at the business, newest first, and why.\n\n- `ai_handoff`: the AI told them the team would get back to them and nobody has written, called or booked them since (`question` is what it couldn't answer, `asked_again` when they chased it).\n- `missed_call`: they called and nobody picked up or called back (`voicemail`, `message_taken` by the AI receptionist, `call_note`).\n- `message`: their message has no reply from a person or the AI (reminders, follow-ups and automations aren't replies; a thanks or ok after a message that asked nothing needs none; with AI replies on, a brand-new message is the AI's for its first 3 minutes).\n- `total`, `by_reason` and `longest_since` count everyone; `leads` lists up to `limit`.\n- Technicians and limited Staff see only their own leads.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many people to list, 1-100, default 25.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "total": 3,
                    "longest_since": "2026-10-28T14:10:00Z",
                    "by_reason": {
                      "ai_handoff": 1,
                      "missed_call": 1,
                      "message": 1
                    },
                    "leads": [
                      {
                        "lead_id": "uuid",
                        "name": "Jane Doe",
                        "phone": "+14155550123",
                        "reason": "ai_handoff",
                        "since": "2026-10-28T14:10:00Z",
                        "last_at": "2026-10-28T16:40:00Z",
                        "question": "Do you install skylights?",
                        "preview": "Any update?",
                        "channel": "sms",
                        "asked_again": true,
                        "called": false,
                        "voicemail": false,
                        "message_taken": false,
                        "call_note": null,
                        "ai_out_of_replies": false
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calls": {
      "get": {
        "operationId": "list_calls",
        "tags": [
          "Calls"
        ],
        "summary": "Phone calls, newest first",
        "description": "Every call on the sub-account's numbers: direction, type (softphone, bridge, inbound, forward, ai, `ai_receptionist`), status, duration, voicemail, the AI's outcome and summary, and the lead. Get one for its transcript and recording.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Inbound or outbound.",
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Call type.",
            "schema": {
              "type": "string",
              "enum": [
                "softphone",
                "bridge",
                "inbound",
                "forward",
                "ai",
                "ai_receptionist"
              ]
            }
          },
          {
            "name": "outcome",
            "in": "query",
            "required": false,
            "description": "The Calls tab's outcome filter.",
            "schema": {
              "type": "string",
              "enum": [
                "connected",
                "missed",
                "voicemail"
              ]
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "One lead's calls.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO time, calls at or after.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "ISO time, calls before.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "calls": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "lead_id": "uuid",
                        "direction": "inbound",
                        "mode": "ai_receptionist",
                        "status": "completed",
                        "from_number": "+14155550123",
                        "to_number": "+14155550199",
                        "answered_at": "2026-09-30T15:00:04Z",
                        "ended_at": "2026-09-30T15:03:10Z",
                        "duration_sec": 186,
                        "is_voicemail": false,
                        "voicemail_read_at": null,
                        "ai_outcome": "booked",
                        "ai_summary": "Caller wanted a roof inspection; booked Thursday 2pm.",
                        "ai_booking_id": "uuid",
                        "campaign_id": null,
                        "created_at": "2026-09-30T15:00:00Z",
                        "ai_call": true,
                        "has_recording": true,
                        "lead": {
                          "id": "uuid",
                          "full_name": "Jane Doe",
                          "phone": "+14155550123"
                        }
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/calls/{call_id}": {
      "get": {
        "operationId": "get_call",
        "tags": [
          "Calls"
        ],
        "summary": "One call: summary, transcript and recording",
        "description": "`recording.url` is a fresh link that works for 15 minutes; ask again for a new one.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "description": "Call id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "call": {
                      "id": "uuid",
                      "direction": "inbound",
                      "mode": "ai_receptionist",
                      "status": "completed",
                      "duration_sec": 186,
                      "ai_outcome": "booked",
                      "ai_summary": "Caller wanted a roof inspection; booked Thursday 2pm.",
                      "transcript": "AI: Thanks for calling...\nCaller: Hi, I need...",
                      "recording": {
                        "url": "https://.../lead-media/...mp3?token=...",
                        "expires_at": "2026-09-30T15:20:00Z",
                        "expires_in_seconds": 900
                      },
                      "lead": {
                        "id": "uuid",
                        "full_name": "Jane Doe",
                        "phone": "+14155550123"
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-campaigns/{campaign_id}/pause": {
      "post": {
        "operationId": "pause_call_campaign",
        "tags": [
          "Calls"
        ],
        "summary": "Pause a running AI calling campaign",
        "description": "Its queued calls are cancelled. Resuming places paid calls, so it is done in the app. 409 when it is not running.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-lessons": {
      "get": {
        "operationId": "list_ai_lessons",
        "tags": [
          "AI Brain"
        ],
        "summary": "What the team has taught the AI",
        "description": "Settings → AI Brain: rules (instructions every AI reply follows), good examples (thumbs up) and lessons (thumbs down: what was wrong, a better reply, never send anything like it again). The AI texter and the voice agent read the active ones on every reply.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only this kind.",
            "schema": {
              "type": "string",
              "enum": [
                "good",
                "avoid",
                "rule"
              ]
            }
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "description": "Only switched on (true) or off (false).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 50.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lessons": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "kind": "rule",
                        "channel": "sms",
                        "ai_message": null,
                        "lead_message": null,
                        "better_reply": null,
                        "reasons": [],
                        "note": "Never quote prices by text.",
                        "never_again": false,
                        "source": "brain",
                        "lead_id": null,
                        "active": true,
                        "created_at": "2026-09-30T12:00:00Z",
                        "updated_at": "2026-09-30T12:00:00Z",
                        "message_id": null
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_ai_lesson",
        "tags": [
          "AI Brain"
        ],
        "summary": "Add a rule the AI follows",
        "description": "Like Add rule in Settings → AI Brain. channel limits it to texts (sms), email or calls (voice); leave it out for everywhere. To teach from a specific reply, rate it (`POST /v1/messages/{message_id}/rating`).\n\nWho can call it: Owners and admins only; at most 200 rules.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "note": {
                    "type": "string",
                    "description": "The rule, max 600 characters."
                  },
                  "channel": {
                    "type": "string",
                    "description": "Where it applies. Default everywhere.",
                    "enum": [
                      "sms",
                      "email",
                      "voice",
                      "all"
                    ]
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Default true."
                  }
                },
                "required": [
                  "workspace_id",
                  "note"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "note": "Never quote prices by text; offer a free estimate visit instead.",
                "channel": "sms"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-lessons/{lesson_id}": {
      "patch": {
        "operationId": "update_ai_lesson",
        "tags": [
          "AI Brain"
        ],
        "summary": "Switch a lesson off or reword it",
        "description": "What can change depends on the kind, as in the app: a rule's note, channel and active; a thumbs-down lesson's note, `better_reply`, `never_again` and active; a good example's active only.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lesson_id",
            "in": "path",
            "required": true,
            "description": "Lesson id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "active": {
                    "type": "boolean",
                    "description": "On or off."
                  },
                  "note": {
                    "type": "string",
                    "description": "Max 600."
                  },
                  "channel": {
                    "type": "string",
                    "description": "Rules only.",
                    "enum": [
                      "sms",
                      "email",
                      "voice",
                      "all"
                    ]
                  },
                  "better_reply": {
                    "type": "string",
                    "description": "Thumbs-down lessons only, max 2000."
                  },
                  "never_again": {
                    "type": "boolean",
                    "description": "Thumbs-down lessons only."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "active": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_ai_lesson",
        "tags": [
          "AI Brain"
        ],
        "summary": "Delete a lesson for good",
        "description": "active: false on PATCH keeps it but switches it off.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lesson_id",
            "in": "path",
            "required": true,
            "description": "Lesson id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/messages/{message_id}/rating": {
      "post": {
        "operationId": "rate_ai_message",
        "tags": [
          "AI Brain"
        ],
        "summary": "Thumbs up or down on an AI message",
        "description": "Exactly the Inbox's rating. up keeps the reply as a good example; down records what was wrong (reasons), what it should have said (`better_reply`), a note, and by default never to send anything close again; clear removes the rating.\n\n- Rating the same message again replaces its lesson.\n- Works on messages and calls sent to the lead (message ids from `GET /v1/leads/{lead_id}/conversation`).\n\nWho can call it: Owners and admins only.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "description": "The message (lead event) id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "rating": {
                    "type": "string",
                    "description": "up, down or clear.",
                    "enum": [
                      "up",
                      "down",
                      "clear"
                    ]
                  },
                  "reasons": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "down only: wrong_info, too_pushy, too_long, missed_question, wrong_tone, should_not_reply."
                  },
                  "better_reply": {
                    "type": "string",
                    "description": "down only: what it should have said (max 2000)."
                  },
                  "note": {
                    "type": "string",
                    "description": "down only: a note (max 600)."
                  },
                  "never_again": {
                    "type": "boolean",
                    "description": "down only. Default true."
                  }
                },
                "required": [
                  "rating"
                ],
                "additionalProperties": true
              },
              "example": {
                "rating": "down",
                "reasons": [
                  "too_pushy"
                ],
                "better_reply": "No rush at all, happy to answer any questions first."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "message_id": "uuid",
                    "rating": "down",
                    "lesson_id": "uuid",
                    "lesson": {
                      "id": "uuid",
                      "kind": "avoid",
                      "channel": "sms",
                      "ai_message": "Book now before slots fill up!",
                      "better_reply": "No rush at all, happy to answer any questions first.",
                      "reasons": [
                        "too_pushy"
                      ],
                      "never_again": true,
                      "active": true
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/phone-numbers": {
      "get": {
        "operationId": "list_phone_numbers",
        "tags": [
          "Setup"
        ],
        "summary": "The sub-account's phone numbers",
        "description": "Number, name, default, capabilities, texting registration and caller-name status, and who may use it: `assigned_user_id` (a number that belongs to one team member: it rings only them and other technicians can't text from it), `tech_can_answer` and `tech_can_use` (whether it rings technicians and whether they may call and text from it), and `ring_in_order` (its calls ring the team one after another, set in the app under Settings > Phone).\n\n- Buying and releasing numbers is done in the app.\n- iMessage Macs: `GET /v1/imessage/lines`.\n\nRequired scope: `phone_numbers:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_released",
            "in": "query",
            "required": false,
            "description": "Include released numbers.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "phone_numbers": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "phone_number": "+14155550199",
                        "friendly_name": "Main line",
                        "is_default": true,
                        "capabilities": {
                          "sms": true,
                          "voice": true,
                          "mms": true
                        },
                        "sms_registration_status": "ready",
                        "cnam_display_name": "ACME ROOFING",
                        "cnam_status": "approved",
                        "shaken_status": null,
                        "voice_forward_enabled": false,
                        "created_at": "2026-09-01T00:00:00Z",
                        "released_at": null,
                        "texting_ready": true,
                        "ring_in_order": false
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/stripe/payments": {
      "get": {
        "operationId": "list_stripe_payments",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Payments from the business's own Stripe",
        "description": "With Track payments on (Settings > Integrations > Stripe), every paid Payment Link or checkout the business made in its own Stripe is recorded, matched to a lead (the link's `client_reference_id` = the lead id, then email, then phone), moves that lead to `payment_stage_key` (never backwards) and is sent to Meta as `payment_meta_event`.\n\n- connection is the setting (null = Stripe not connected; listening = our webhook is on their Stripe account); payments are the ones recorded, newest first: `lead_action` is moved, already, kept (it was further along), none or `no_lead`; `meta_status` is sent, queued, failed, off, `no_dataset` or `no_login`.\n- The Stripe key and webhook details are never returned.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "One lead's payments.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "connection": {
                      "connected": true,
                      "status": "connected",
                      "livemode": true,
                      "account_name": "Acme Roofing",
                      "last_error": null,
                      "collect_on_invoices": true,
                      "track_payments": true,
                      "listening": true,
                      "payment_stage_key": "booked",
                      "payment_meta_event": "Purchase",
                      "webhook_error": null,
                      "updated_at": "2026-11-01T15:00:00Z"
                    },
                    "payments": [
                      {
                        "id": "uuid",
                        "amount_cents": 15000,
                        "currency": "usd",
                        "email": "jane@example.com",
                        "name": "Jane Doe",
                        "livemode": true,
                        "paid_at": "2026-11-02T18:04:00Z",
                        "refunded_at": null,
                        "payment_link_id": "plink_123",
                        "lead_id": "uuid",
                        "lead_name": "Jane Doe",
                        "matched_by": "email",
                        "lead_action": "moved",
                        "stage_key": "booked",
                        "meta_event": "Purchase",
                        "meta_status": "sent",
                        "meta_error": null
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/stripe/payment-tracking": {
      "patch": {
        "operationId": "set_stripe_payment_tracking",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Turn Stripe payment tracking on or off",
        "description": "on: true adds our webhook endpoint to the business's connected Stripe account (the key needs Webhook Endpoints: Write) and false removes it; payments already recorded stay.\n\n- `stage_key` is the pipeline stage a paying lead moves to (any stage the sub-account shows except lost; null leaves the lead where it is); `meta_event` is what the sub-account's Meta dataset gets (Purchase with the amount, Schedule, or null for nothing).\n- Send any of the three; the rest stay as they are.\n- 409 when Stripe isn't connected (connect it in the app).\n- Answers with the connection as `GET /v1/stripe/payments` shows it.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "on": {
                    "type": "boolean",
                    "description": "Track payments, or stop."
                  },
                  "stage_key": {
                    "type": "string",
                    "description": "Where a paying lead moves (GET /v1/stages), or null to leave it."
                  },
                  "meta_event": {
                    "type": "string",
                    "description": "What Meta gets, or null.",
                    "enum": [
                      "Purchase",
                      "Schedule"
                    ]
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "on": true,
                "stage_key": "booked",
                "meta_event": "Purchase"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "connection": {
                      "connected": true,
                      "status": "connected",
                      "livemode": true,
                      "account_name": "Acme Roofing",
                      "last_error": null,
                      "collect_on_invoices": true,
                      "track_payments": true,
                      "listening": true,
                      "payment_stage_key": "booked",
                      "payment_meta_event": "Purchase",
                      "webhook_error": null,
                      "updated_at": "2026-11-03T10:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/estimates": {
      "get": {
        "operationId": "list_estimates",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Estimates (read only)",
        "description": "The sub-account's estimates, newest first, as the Estimates tab lists them: number, title, the customer, status and `effective_status` (expired: sent and past its last day), when it was sent, viewed, approved (and by whom) or declined (and why), the invoice it became, its Good / Better / Best options with their totals, and `total_cents` (the option the customer picked, else the recommended one).\n\n- With Quote templates (Settings > Features) each also says the template it started from (`template_id`), what approving does (`on_approve`, `approval_steps` in words), the booking calendar (`booking_calendar_id`), whether the customer signed (signed; the drawing itself never leaves) and the total they agreed to with their add-ons (`approved_total_cents`); these are null / false otherwise.\n- Technicians and Staff limited to their own leads see the estimates for leads they can see and ones they made without a lead, as in the app.\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "sent",
                "approved",
                "declined",
                "expired",
                "converted"
              ]
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "One lead's estimates.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "estimates": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "lead_id": "uuid",
                        "number": "EST-001042",
                        "title": "Duct cleaning, whole house",
                        "status": "sent",
                        "currency": "usd",
                        "issue_date": "2026-10-20",
                        "expires_at": "2026-11-19",
                        "customer_name": "Jane Doe",
                        "customer_email": "jane@example.com",
                        "customer_phone": "+14155550123",
                        "selected_option_id": null,
                        "sent_at": "2026-10-20T16:00:00Z",
                        "viewed_at": "2026-10-20T18:12:00Z",
                        "approved_at": null,
                        "approved_by_name": null,
                        "declined_at": null,
                        "decline_reason": null,
                        "converted_invoice_id": null,
                        "created_by": "uuid",
                        "created_at": "2026-10-20T15:40:00Z",
                        "updated_at": "2026-10-20T18:12:00Z",
                        "effective_status": "sent",
                        "total_cents": 64900,
                        "template_id": null,
                        "on_approve": null,
                        "approval_steps": [],
                        "booking_calendar_id": null,
                        "signed": false,
                        "approved_total_cents": null,
                        "options": [
                          {
                            "id": "uuid",
                            "name": "Good",
                            "is_recommended": false,
                            "total_cents": 39900
                          },
                          {
                            "id": "uuid",
                            "name": "Better",
                            "is_recommended": true,
                            "total_cents": 64900
                          }
                        ]
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_estimate",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Create an estimate (draft)",
        "description": "Saved as a draft exactly as the estimate editor saves one: the sub-account's next number, its default terms, days valid and tax rate, the lead's name, email, phone and address filled in.\n\n- Send items for one option, or options (2-5, e.g. Good / Better / Best) each with its items; every option's subtotal, tax and total are worked out as the editor does (each line rounded, tax on taxable lines; an add-on line counts only once the customer picks it).\n- With Quote templates on (Settings > Features), `template_id` starts it from a saved quote (its title, intro, terms, days valid, options and lines, `on_approve` and booking calendar) and anything else you send replaces the template's (items or options replace all its lines); lines can be add-ons (optional) and `on_approve` says what approving does.\n- Those fields answer 403 `feature_off` while Quote templates is off.\n- Answers with the estimate as `GET /v1/estimates/{estimate_id}` shows it.\n- Send it with `POST /v1/estimates/{estimate_id}/send`.\n- Technicians only while the sub-account lets them make estimates, and only for their own leads.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "Who it is for (fills in the customer; needed to send it). Or customer_name."
                  },
                  "template_id": {
                    "type": "string",
                    "description": "Start from this quote template (GET /v1/estimate-templates). Needs Quote templates."
                  },
                  "title": {
                    "type": "string",
                    "description": "Max 200, e.g. Whole-house duct cleaning."
                  },
                  "intro": {
                    "type": "string",
                    "description": "A note to the customer at the top (max 2000)."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "One option's lines: [{ description (the line's name, max 300), details? (max 2000), image_url? (https), quantity? (default 1), unit_price_cents, taxable? (default true), optional? (an add-on the customer may tick, counted once picked; needs Quote templates) }]. At least one line isn't optional."
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Instead of items, up to 5 choices: [{ name, description?, image_url?, recommended?, items: [...] }]. One is recommended (the first marked, else the first)."
                  },
                  "on_approve": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "What approving does: { signature (they draw their signature), invoice: \"none\" | \"draft\" (an invoice waits for you to send) | \"pay\" (they pay it right away), deposit_percent (above 0, below 100) or deposit_cents (a fixed amount; either needs an invoice), mark_won (the lead is marked Won with the total) }, or null for nothing automatic. Default: the template's, else nothing automatic. Needs Quote templates."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "After approving, the customer can book a time on this calendar of the sub-account (GET /v1/calendars), or null. Default: the template's. Needs Quote templates."
                  },
                  "tax_rate": {
                    "type": "number",
                    "description": "Percent, 0-30. Default: the sub-account's."
                  },
                  "valid_days": {
                    "type": "number",
                    "description": "Days it is valid (1-365). Default: the sub-account's. Or expires_at."
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "Last day, YYYY-MM-DD, or null for no end."
                  },
                  "terms": {
                    "type": "string",
                    "description": "Max 4000. Default: the sub-account's estimate terms."
                  },
                  "currency": {
                    "type": "string",
                    "description": "3 letters, default usd."
                  },
                  "customer_name": {
                    "type": "string",
                    "description": "Without a lead, or to change what the lead fills in."
                  },
                  "customer_email": {
                    "type": "string",
                    "description": "Customer email."
                  },
                  "customer_phone": {
                    "type": "string",
                    "description": "Customer phone."
                  },
                  "customer_address": {
                    "type": "string",
                    "description": "Customer address."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_id": "uuid",
                "title": "Duct cleaning",
                "options": [
                  {
                    "name": "Good",
                    "items": [
                      {
                        "description": "Main trunk lines",
                        "unit_price_cents": 29900
                      }
                    ]
                  },
                  {
                    "name": "Better",
                    "recommended": true,
                    "items": [
                      {
                        "description": "Every vent and return",
                        "details": "Up to 20 vents, before and after photos.",
                        "unit_price_cents": 49900
                      }
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/estimates/{estimate_id}": {
      "get": {
        "operationId": "get_estimate",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "One estimate with its options, lines and history",
        "description": "Adds the customer's address, intro, terms, tax rate and the customer's approval note, every option (name, description, photo, recommended, subtotal, tax and total) with its lines (name, details, photo, quantity, unit price, taxable, and with Quote templates optional (an add-on the customer may tick) and picked (they did); an option's totals count its other lines plus the picked add-ons), the history (created, sent, viewed, approved, declined) and `public_path`, the customer's page on the sub-account's domain (none for drafts). Also `template_id`, `on_approve`, `approval_steps`, `booking_calendar_id`, signed and `approved_total_cents` as the list shows them.\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "estimate_id",
            "in": "path",
            "required": true,
            "description": "Estimate id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_estimate",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Change an estimate",
        "description": "Send only what changes. options (or items) replace every option and line, as the editor saves; a new `tax_rate` re-totals the options.\n\n- `on_approve`, `booking_calendar_id` and add-on lines (optional) need Quote templates on (403 `feature_off` otherwise); `template_id` is only for creating.\n- An approved estimate or one already made into an invoice answers 409: make a new one.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "estimate_id",
            "in": "path",
            "required": true,
            "description": "Estimate id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "New title."
                  },
                  "intro": {
                    "type": "string",
                    "description": "New note at the top."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "Or null."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the options with one (lines may be optional add-ons, see create)."
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the options."
                  },
                  "tax_rate": {
                    "type": "number",
                    "description": "Percent, 0-30; re-totals the options."
                  },
                  "valid_days": {
                    "type": "number",
                    "description": "Days valid from today (1-365)."
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "Last day, YYYY-MM-DD, or null."
                  },
                  "terms": {
                    "type": "string",
                    "description": "New terms."
                  },
                  "customer_name": {
                    "type": "string",
                    "description": "Customer name."
                  },
                  "customer_email": {
                    "type": "string",
                    "description": "Customer email."
                  },
                  "customer_phone": {
                    "type": "string",
                    "description": "Customer phone."
                  },
                  "customer_address": {
                    "type": "string",
                    "description": "Customer address."
                  },
                  "on_approve": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "What approving does: { signature (they draw their signature), invoice: \"none\" | \"draft\" (an invoice waits for you to send) | \"pay\" (they pay it right away), deposit_percent (above 0, below 100) or deposit_cents (a fixed amount; either needs an invoice), mark_won (the lead is marked Won with the total) }, or null for nothing automatic. Needs Quote templates."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "A calendar of the sub-account, or null. Needs Quote templates."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "tax_rate": 8.25
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_estimate",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Delete an estimate",
        "description": "One that became an invoice stays (409), so the invoice still points at it.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "estimate_id",
            "in": "path",
            "required": true,
            "description": "Estimate id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/price-book": {
      "get": {
        "operationId": "list_price_book",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "The price book",
        "description": "The saved items estimates and invoices pick their lines from: name, details, category, unit price, taxable, photo, and how often it's used (most used first).\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Name or category contains (2-80 characters).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_inactive",
            "in": "query",
            "required": false,
            "description": "Include archived items.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-500, default 100.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "items": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Dryer vent cleaning",
                        "description": "Brush and vacuum the full run, check the exterior flap.",
                        "category": "Vents",
                        "unit_price_cents": 14900,
                        "taxable": true,
                        "image_url": null,
                        "is_active": true,
                        "usage_count": 37,
                        "last_used_at": "2026-10-22T14:00:00Z",
                        "created_at": "2026-09-01T00:00:00Z",
                        "updated_at": "2026-10-22T14:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/estimates/{estimate_id}/send": {
      "post": {
        "operationId": "send_estimate",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Send an estimate to the lead",
        "description": "Like the editor's Send: a text and/or an email to the estimate's lead with the link to review and approve it (on the sub-account's own domain when it has one), in the editor's own words unless you send message (it must include `{link}`).\n\n- Sent as the key's person, with the usual opt-out, credit and limit checks; each is billed like any text or email.\n- A draft (or a declined or expired one) becomes sent.\n- sent lists each channel and why one didn't go.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "estimate_id",
            "in": "path",
            "required": true,
            "description": "Estimate id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "description": "Default both (whichever the lead has).",
                    "enum": [
                      "sms",
                      "email",
                      "both"
                    ]
                  },
                  "message": {
                    "type": "string",
                    "description": "Your own wording, with {link}."
                  },
                  "subject": {
                    "type": "string",
                    "description": "The email's subject."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "channel": "sms"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sent": [
                      {
                        "channel": "sms",
                        "ok": true
                      }
                    ],
                    "link": "https://book.acme.com/e/abc123",
                    "status": "sent"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/estimates/{estimate_id}/convert": {
      "post": {
        "operationId": "convert_estimate",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Make the invoice",
        "description": "Convert to invoice: a draft invoice from the option the customer picked (else the recommended one, or `option_id`), with its lines (and the add-ons the customer picked, never the ones they left), the estimate's tax rate and the sub-account's due days, terms and notes; the estimate becomes converted. Send the invoice from the app.\n\nWho can call it: Owners and admins (invoices are theirs).\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "estimate_id",
            "in": "path",
            "required": true,
            "description": "Estimate id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "option_id": {
                    "type": "string",
                    "description": "The option to invoice."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "estimate_id": "uuid",
                    "status": "converted",
                    "invoice": {
                      "id": "uuid",
                      "number": "INV-000124",
                      "status": "draft",
                      "total_cents": 49900
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/estimate-templates": {
      "get": {
        "operationId": "list_estimate_templates",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Quote templates",
        "description": "Saved quotes estimates start from, the most used first: name, the estimate title it fills in, shape (options, lines, add-ons), `from_cents` (the recommended option's lines before tax and add-ons), what approving does (`on_approve`, and `approval_steps` in words), the booking calendar, `use_count` and `last_used_at`.\n\n- Everyone who makes estimates reads them.\n- Needs Quote templates on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.quote_templates`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "templates": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Window cleaning, standard house",
                        "title": "Window cleaning",
                        "shape": "2 options · 3 lines · 1 add-on",
                        "from_cents": 29900,
                        "option_count": 2,
                        "on_approve": {
                          "signature": true,
                          "invoice": "pay",
                          "deposit_percent": 25,
                          "deposit_cents": null,
                          "mark_won": true
                        },
                        "approval_steps": [
                          "They sign with their finger or mouse",
                          "They pay a 25% deposit right away",
                          "The lead is marked Won with the total"
                        ],
                        "booking_calendar_id": null,
                        "use_count": 41,
                        "last_used_at": "2026-11-10T15:20:00Z",
                        "updated_at": "2026-11-02T09:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_estimate_template",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Save a quote template",
        "description": "Owners and admins, at most 200 per sub-account. Without `on_approve` a new template asks for a signature, has the customer pay the invoice right away and marks the lead Won, as in the app.\n\n- Make an estimate from it with `POST /v1/estimates` `template_id`.\n- Needs Quote templates on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.quote_templates`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "What the team sees in the list (max 120)."
                  },
                  "title": {
                    "type": "string",
                    "description": "The estimate's title it fills in (max 200)."
                  },
                  "intro": {
                    "type": "string",
                    "description": "A note to the customer at the top (max 2000)."
                  },
                  "terms": {
                    "type": "string",
                    "description": "Max 4000. Empty: the sub-account's estimate terms."
                  },
                  "valid_days": {
                    "type": "number",
                    "description": "Days an estimate made from it is valid (1-365). Empty: the sub-account's default."
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The options with their lines, 1-5 (replaces them all): [{ name, description?, image_url? (https), recommended?, items: [{ description (max 300), details?, image_url? (https), quantity? (default 1), unit_price_cents, taxable? (default true), optional? (an add-on the customer may tick; counts once picked) }] }]. Every option needs at least one line that isn't optional."
                  },
                  "on_approve": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "What approving does: { signature (they draw their signature), invoice: \"none\" | \"draft\" (an invoice waits for you to send) | \"pay\" (they pay it right away), deposit_percent (above 0, below 100) or deposit_cents (a fixed amount; either needs an invoice), mark_won (the lead is marked Won with the total) }, or null for nothing automatic."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "After approving, the customer can book a time on this calendar of the sub-account (GET /v1/calendars), or null."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Window cleaning, standard house",
                "title": "Window cleaning",
                "options": [
                  {
                    "name": "Outside only",
                    "items": [
                      {
                        "description": "Exterior windows, up to 20",
                        "unit_price_cents": 19900
                      }
                    ]
                  },
                  {
                    "name": "Inside and out",
                    "recommended": true,
                    "items": [
                      {
                        "description": "Every window, both sides",
                        "unit_price_cents": 29900
                      },
                      {
                        "description": "Screens washed",
                        "unit_price_cents": 4900,
                        "optional": true
                      }
                    ]
                  }
                ],
                "on_approve": {
                  "signature": true,
                  "invoice": "pay",
                  "deposit_percent": 25,
                  "mark_won": true
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "template": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Window cleaning, standard house",
                      "title": "Window cleaning",
                      "shape": "2 options · 3 lines · 1 add-on",
                      "from_cents": 29900,
                      "option_count": 2,
                      "on_approve": {
                        "signature": true,
                        "invoice": "pay",
                        "deposit_percent": 25,
                        "deposit_cents": null,
                        "mark_won": true
                      },
                      "approval_steps": [
                        "They sign with their finger or mouse",
                        "They pay a 25% deposit right away",
                        "The lead is marked Won with the total"
                      ],
                      "booking_calendar_id": null,
                      "use_count": 41,
                      "last_used_at": "2026-11-10T15:20:00Z",
                      "updated_at": "2026-11-02T09:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/estimate-templates/{template_id}": {
      "get": {
        "operationId": "get_estimate_template",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "One quote template with its lines",
        "description": "Adds intro, terms, `valid_days` and the options with every line (prices in cents; optional = an add-on the customer may tick). Needs Quote templates on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.quote_templates`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `billing:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "description": "Template id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_estimate_template",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Change a quote template",
        "description": "Owners and admins. Send only what changes; options replace them all.\n\n- Estimates already made from it keep what they copied.\n- Needs Quote templates on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.quote_templates`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "description": "Template id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "New name."
                  },
                  "title": {
                    "type": "string",
                    "description": "New title."
                  },
                  "intro": {
                    "type": "string",
                    "description": "New note at the top."
                  },
                  "terms": {
                    "type": "string",
                    "description": "New terms."
                  },
                  "valid_days": {
                    "type": "number",
                    "description": "1-365, or null."
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Replaces the options (see create)."
                  },
                  "on_approve": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "What approving does: { signature (they draw their signature), invoice: \"none\" | \"draft\" (an invoice waits for you to send) | \"pay\" (they pay it right away), deposit_percent (above 0, below 100) or deposit_cents (a fixed amount; either needs an invoice), mark_won (the lead is marked Won with the total) }, or null for nothing automatic."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "A calendar of the sub-account, or null."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "on_approve": {
                  "signature": true,
                  "invoice": "draft",
                  "mark_won": false
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_estimate_template",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Delete a quote template",
        "description": "Owners and admins. Estimates made from it keep everything they copied. Needs Quote templates on in Settings > Features (`PATCH /v1/workspaces/{workspace_id}` with `enabled_features.quote_templates`); while it's off this answers 403 `feature_off`.\n\nRequired scope: `billing:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "description": "Template id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-campaigns": {
      "get": {
        "operationId": "list_email_campaigns",
        "tags": [
          "Email marketing"
        ],
        "summary": "Email campaigns and their results",
        "description": "The sub-account's marketing emails, most recently changed first, as Tools > Email Marketing lists them: status (draft, scheduled, sending, sent, failed, canceled), subject, who it goes to, the pace (drip: every emails a batch, minutes between batches; null = all at once), how far it got and the results (delivered, opened, clicked, booked, booked after a click, unsubscribed, bounced).\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "scheduled",
                "sending",
                "sent",
                "failed",
                "canceled"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "campaigns": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Fall tune-up",
                        "status": "sent",
                        "subject": "Your $49 tune-up is back",
                        "audience": "tags",
                        "stages": [],
                        "tags": [
                          "uuid"
                        ],
                        "not_booked": true,
                        "drip": {
                          "every": 50,
                          "minutes": 60
                        },
                        "scheduled_at": null,
                        "started_at": "2026-10-20T15:00:00Z",
                        "sent_at": "2026-10-21T02:00:00Z",
                        "next_batch_at": null,
                        "total_recipients": 540,
                        "sent_count": 532,
                        "failed_count": 2,
                        "skipped_count": 6,
                        "credits_charged": 1.6,
                        "error": null,
                        "results": {
                          "recipients": 540,
                          "queued": 0,
                          "sent": 532,
                          "failed": 2,
                          "delivered": 528,
                          "opened": 241,
                          "clicked": 63,
                          "booked": 9,
                          "booked_after_click": 7,
                          "unsubscribed": 3,
                          "bounced": 4
                        },
                        "created_at": "2026-10-19T18:00:00Z",
                        "updated_at": "2026-10-21T02:00:00Z"
                      }
                    ],
                    "has_more": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_email_campaign",
        "tags": [
          "Email marketing"
        ],
        "summary": "Create an email campaign (draft)",
        "description": "With brief, the AI designs and writes the whole email from one or two sentences, as Write it for me does (it can take a minute or two), and suggests an audience (`suggested_audience`); pictures: true also makes AI header pictures (0.5 credits each, three a round).\n\n- Without, a draft from the business's own details and the content you send.\n- The button goes to destination (default: the newest published Smart Page, else a booking form) or `button_url`.\n- Nothing is sent.\n\nWho can call it: Owners and admins.\n\nRequired scope: `messaging:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Your name for it (max 120)."
                  },
                  "brief": {
                    "type": "string",
                    "description": "What the email is about: the offer, the deadline, who it's for (4-4000 characters). Not with the content fields."
                  },
                  "pictures": {
                    "type": "boolean",
                    "description": "With brief: AI header pictures (spends credits). Default false."
                  },
                  "destination": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Where the button goes: { kind: smart_page | smart_form, id }, { kind: url, url } or { kind: none }."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Max 150."
                  },
                  "preheader": {
                    "type": "string",
                    "description": "The preview line inboxes show after the subject (max 200)."
                  },
                  "eyebrow": {
                    "type": "string",
                    "description": "A small label above the headline (max 40)."
                  },
                  "headline": {
                    "type": "string",
                    "description": "Max 160."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "e.g. Hi {first_name}, (max 80)."
                  },
                  "body": {
                    "type": "string",
                    "description": "The words in markdown (## headings, - bullets, **bold**, [links](https://...)), max 12000. Replaces every section with one text section."
                  },
                  "blocks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Instead of body, up to 24 sections as GET shows them: text {md}, offer {value, label, was, note, kicker}, image {url}, split {url, title, md}, features / steps {title, items}, quote {text, name, stars}, gallery {images}, banner {text}, faq {items: [{q, a}]}, cards {items}, button {label, url}, divider, html {html} (email-safe HTML), game {gameId, headline, text, button} (one of the sub-account's reward games: its picture and a play button; each reader who clicks gets their own play)."
                  },
                  "button_label": {
                    "type": "string",
                    "description": "The main button (max 50)."
                  },
                  "button_url": {
                    "type": "string",
                    "description": "Where it goes: a full http(s) link."
                  },
                  "hero_image_url": {
                    "type": "string",
                    "description": "An https picture at the top, or empty to remove it."
                  },
                  "hero_image_alt": {
                    "type": "string",
                    "description": "Its description."
                  },
                  "signoff": {
                    "type": "string",
                    "description": "e.g. Talk soon,"
                  },
                  "signer_name": {
                    "type": "string",
                    "description": "Who signs it."
                  },
                  "signer_title": {
                    "type": "string",
                    "description": "Their title."
                  },
                  "ps": {
                    "type": "string",
                    "description": "A P.S. under the signature (max 600)."
                  },
                  "design": {
                    "type": "string",
                    "description": "The look.",
                    "enum": [
                      "classic",
                      "bold",
                      "letter",
                      "flyer",
                      "newsletter",
                      "elegant",
                      "minimal",
                      "bright",
                      "fresh",
                      "blocks",
                      "retro",
                      "night",
                      "soft"
                    ]
                  },
                  "show_logo": {
                    "type": "boolean",
                    "description": "Design > Logo at the top: false leaves the logo and business name off the top of the email (when a picture or your own header already shows them); true puts them back. Works with brief too."
                  },
                  "html": {
                    "type": "string",
                    "description": "Your own HTML (a whole email, max 250,000 characters): sent as written instead of the designed email, with subject and preheader still applied. Scripts are taken out; {first_name}, {business} and {unsubscribe_link} are filled in, and without an unsubscribe link a footer with the business's address and one is added. Send an empty string to go back to the designed email."
                  },
                  "audience": {
                    "type": "string",
                    "description": "Who gets it: everyone with an email address, everyone who hasn't booked, leads in some stages, or leads with any of some tags.",
                    "enum": [
                      "everyone",
                      "not_booked",
                      "stages",
                      "tags"
                    ]
                  },
                  "stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "audience stages: stage keys (GET /v1/stages)."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "audience tags: tag names or ids (GET /v1/tags)."
                  },
                  "not_booked": {
                    "type": "boolean",
                    "description": "audience tags: only those who haven't booked."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "brief": "$49 furnace tune-up through November 15, for past customers",
                "design": "fresh"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-campaigns/{campaign_id}": {
      "get": {
        "operationId": "get_email_campaign",
        "tags": [
          "Email marketing"
        ],
        "summary": "One email campaign",
        "description": "Adds its content (subject, preheader, headline, sections in blocks, the button, signature, design), where the button goes (destination), problems (what still blocks sending; `ready_to_send` when there are none) and the header pictures' status.\n\nRequired scope: `messaging:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_email_campaign",
        "tags": [
          "Email marketing"
        ],
        "summary": "Change a draft",
        "description": "Send only what changes, as the builder saves it; brief has the AI rewrite the whole draft instead. A campaign that was sent or scheduled answers 409: duplicate it.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "New name."
                  },
                  "brief": {
                    "type": "string",
                    "description": "The AI rewrites the draft from this (not with the content fields)."
                  },
                  "pictures": {
                    "type": "boolean",
                    "description": "With brief: new AI header pictures (spends credits)."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Max 150."
                  },
                  "preheader": {
                    "type": "string",
                    "description": "The preview line inboxes show after the subject (max 200)."
                  },
                  "eyebrow": {
                    "type": "string",
                    "description": "A small label above the headline (max 40)."
                  },
                  "headline": {
                    "type": "string",
                    "description": "Max 160."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "e.g. Hi {first_name}, (max 80)."
                  },
                  "body": {
                    "type": "string",
                    "description": "The words in markdown (## headings, - bullets, **bold**, [links](https://...)), max 12000. Replaces every section with one text section."
                  },
                  "blocks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Instead of body, up to 24 sections as GET shows them: text {md}, offer {value, label, was, note, kicker}, image {url}, split {url, title, md}, features / steps {title, items}, quote {text, name, stars}, gallery {images}, banner {text}, faq {items: [{q, a}]}, cards {items}, button {label, url}, divider, html {html} (email-safe HTML), game {gameId, headline, text, button} (one of the sub-account's reward games: its picture and a play button; each reader who clicks gets their own play)."
                  },
                  "button_label": {
                    "type": "string",
                    "description": "The main button (max 50)."
                  },
                  "button_url": {
                    "type": "string",
                    "description": "Where it goes: a full http(s) link."
                  },
                  "hero_image_url": {
                    "type": "string",
                    "description": "An https picture at the top, or empty to remove it."
                  },
                  "hero_image_alt": {
                    "type": "string",
                    "description": "Its description."
                  },
                  "signoff": {
                    "type": "string",
                    "description": "e.g. Talk soon,"
                  },
                  "signer_name": {
                    "type": "string",
                    "description": "Who signs it."
                  },
                  "signer_title": {
                    "type": "string",
                    "description": "Their title."
                  },
                  "ps": {
                    "type": "string",
                    "description": "A P.S. under the signature (max 600)."
                  },
                  "design": {
                    "type": "string",
                    "description": "The look.",
                    "enum": [
                      "classic",
                      "bold",
                      "letter",
                      "flyer",
                      "newsletter",
                      "elegant",
                      "minimal",
                      "bright",
                      "fresh",
                      "blocks",
                      "retro",
                      "night",
                      "soft"
                    ]
                  },
                  "show_logo": {
                    "type": "boolean",
                    "description": "Design > Logo at the top: false leaves the logo and business name off the top of the email (when a picture or your own header already shows them); true puts them back. Works with brief too."
                  },
                  "html": {
                    "type": "string",
                    "description": "Your own HTML (a whole email, max 250,000 characters): sent as written instead of the designed email, with subject and preheader still applied. Scripts are taken out; {first_name}, {business} and {unsubscribe_link} are filled in, and without an unsubscribe link a footer with the business's address and one is added. Send an empty string to go back to the designed email."
                  },
                  "audience": {
                    "type": "string",
                    "description": "Who gets it: everyone with an email address, everyone who hasn't booked, leads in some stages, or leads with any of some tags.",
                    "enum": [
                      "everyone",
                      "not_booked",
                      "stages",
                      "tags"
                    ]
                  },
                  "stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "audience stages: stage keys (GET /v1/stages)."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "audience tags: tag names or ids (GET /v1/tags)."
                  },
                  "not_booked": {
                    "type": "boolean",
                    "description": "audience tags: only those who haven't booked."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "subject": "Last call: $49 tune-ups end Friday",
                "audience": "not_booked"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_email_campaign",
        "tags": [
          "Email marketing"
        ],
        "summary": "Delete an email campaign",
        "description": "A scheduled or sending one answers 409: stop it first.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-campaigns/{campaign_id}/send": {
      "post": {
        "operationId": "send_email_campaign",
        "tags": [
          "Email marketing"
        ],
        "summary": "Send or schedule a draft",
        "description": "Emails real people. As the Send button: to the saved audience (or the one you send), now or at `schedule_at`, all at once or a few at a time (drip).\n\n- Left out: leads with no email address, who unsubscribed, bounced or marked it spam.\n- Each email costs messaging credits (none through the business's own email server); a send the credits don't cover answers 402 before anything goes out.\n- A draft is sent once: a second call answers 409.\n- recipients is how many it goes to.\n\nRequired scope: `messaging:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "audience": {
                    "type": "string",
                    "description": "Who gets it: everyone with an email address, everyone who hasn't booked, leads in some stages, or leads with any of some tags.",
                    "enum": [
                      "everyone",
                      "not_booked",
                      "stages",
                      "tags"
                    ]
                  },
                  "stages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "audience stages: stage keys (GET /v1/stages)."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "audience tags: tag names or ids (GET /v1/tags)."
                  },
                  "not_booked": {
                    "type": "boolean",
                    "description": "audience tags: only those who haven't booked."
                  },
                  "schedule_at": {
                    "type": "string",
                    "description": "ISO 8601 with a time zone, 2 minutes to 90 days ahead. Leave out to send now."
                  },
                  "drip": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "A few at a time: { every: 1-10000 emails, minutes: 5-43200 between batches }. The whole send must fit in 90 days."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "audience": "tags",
                "tags": [
                  "Past customer"
                ],
                "schedule_at": "2026-11-03T09:00:00-05:00",
                "drip": {
                  "every": 100,
                  "minutes": 60
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "campaign": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "name": "Fall tune-up",
                      "status": "scheduled",
                      "subject": "Your $49 tune-up is back",
                      "audience": "tags",
                      "stages": [],
                      "tags": [
                        "uuid"
                      ],
                      "not_booked": true,
                      "drip": {
                        "every": 50,
                        "minutes": 60
                      },
                      "scheduled_at": null,
                      "started_at": "2026-10-20T15:00:00Z",
                      "sent_at": "2026-10-21T02:00:00Z",
                      "next_batch_at": null,
                      "total_recipients": 540,
                      "sent_count": 532,
                      "failed_count": 2,
                      "skipped_count": 6,
                      "credits_charged": 1.6,
                      "error": null,
                      "results": null,
                      "created_at": "2026-10-19T18:00:00Z",
                      "updated_at": "2026-10-21T02:00:00Z"
                    },
                    "scheduled": true,
                    "recipients": 540
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-campaigns/{campaign_id}/cancel": {
      "post": {
        "operationId": "cancel_email_campaign",
        "tags": [
          "Email marketing"
        ],
        "summary": "Stop a send",
        "description": "A scheduled campaign goes back to draft; one that is sending stops (the emails not yet sent are skipped).\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-campaigns/{campaign_id}/send-rest": {
      "post": {
        "operationId": "send_email_campaign_rest",
        "tags": [
          "Email marketing"
        ],
        "summary": "Send the rest now",
        "description": "A campaign going out a few at a time: everyone still waiting gets it now. Emails real people.\n\nRequired scope: `messaging:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/email-campaigns/{campaign_id}/duplicate": {
      "post": {
        "operationId": "duplicate_email_campaign",
        "tags": [
          "Email marketing"
        ],
        "summary": "Duplicate a campaign",
        "description": "A new draft with the same content, audience and pace, to change and send again.\n\nRequired scope: `messaging:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "description": "Campaign id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/contracts": {
      "get": {
        "operationId": "list_contracts",
        "tags": [
          "Contracts"
        ],
        "summary": "Contracts",
        "description": "The sub-account's contracts, newest first: who signs (lead and recipient), status (draft, sent, signed, declined, voided) and stage as the page shows it (draft, sent, viewed, signed, completed when you countersigned, declined, voided, expired), when it was sent, opened, signed or declined (and why), the onboarding call it booked, and `sign_url` once it is out of draft.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "sent",
                "signed",
                "declined",
                "voided"
              ]
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "One lead's contracts.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "next_before from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "contracts": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "lead_id": "uuid",
                        "template_id": "uuid",
                        "recipient_name": "Jane Doe",
                        "recipient_email": "jane@example.com",
                        "recipient_phone": "+14155550123",
                        "subject": "Service agreement",
                        "status": "sent",
                        "stage": "viewed",
                        "sent_at": "2026-10-28T16:00:00Z",
                        "last_sent_at": "2026-10-28T16:00:00Z",
                        "send_count": 1,
                        "viewed_at": "2026-10-28T16:20:00Z",
                        "last_viewed_at": "2026-10-28T16:20:00Z",
                        "view_count": 2,
                        "signed_at": null,
                        "signer_name": null,
                        "agency_signed_at": null,
                        "declined_at": null,
                        "decline_reason": null,
                        "voided_at": null,
                        "expires_at": null,
                        "booking_enabled": false,
                        "booking_calendar_id": null,
                        "booking_id": null,
                        "booked_at": null,
                        "created_by": "uuid",
                        "created_at": "2026-10-28T15:58:00Z",
                        "updated_at": "2026-10-28T16:20:00Z",
                        "sign_url": "https://app.acme.com/sign/abc123"
                      }
                    ],
                    "has_more": false,
                    "next_before": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_contract",
        "tags": [
          "Contracts"
        ],
        "summary": "Create a contract (draft)",
        "description": "Saved as a draft, as New contract saves one.\n\n- From a template (`template_id`, with values for its blanks; the template's onboarding call setting comes along) or from your own text (body in markdown: # headings, paragraphs, - lists, **bold**, at least 40 characters).\n- The lead's name, email, phone and address, the business's name and today's date fill in by themselves; recipient_* are for a contract without a lead.\n- Nothing is sent: share it with `POST /v1/contracts/{contract_id}/link` or send it with /send (which needs a lead).\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "Who signs."
                  },
                  "template_id": {
                    "type": "string",
                    "description": "From this template (GET /v1/contract-templates). Or body."
                  },
                  "values": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ blank: value } for the template's {{blanks}} (up to 2000 characters each)."
                  },
                  "body": {
                    "type": "string",
                    "description": "Instead of a template: the contract's text in markdown (max 60000)."
                  },
                  "subject": {
                    "type": "string",
                    "description": "The title (max 200). Default: the template's name, or the text's first line."
                  },
                  "recipient_name": {
                    "type": "string",
                    "description": "Without a lead."
                  },
                  "recipient_email": {
                    "type": "string",
                    "description": "Without a lead."
                  },
                  "recipient_phone": {
                    "type": "string",
                    "description": "Without a lead."
                  },
                  "expires_in_days": {
                    "type": "number",
                    "description": "The signing link stops working after this many days (1-365). Default: never."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "lead_id": "uuid",
                "template_id": "uuid",
                "values": {
                  "start_date": "November 3",
                  "price": "$1,200"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/contracts/{contract_id}": {
      "get": {
        "operationId": "get_contract",
        "tags": [
          "Contracts"
        ],
        "summary": "One contract",
        "description": "Adds its text (`body_html`), the values filled in, the `{{blanks}}` left and its history (created, sent, resent with the channels, viewed, signed, declined, voided).\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "contract_id",
            "in": "path",
            "required": true,
            "description": "Contract id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/contracts/{contract_id}/link": {
      "post": {
        "operationId": "get_contract_link",
        "tags": [
          "Contracts"
        ],
        "summary": "Get the signing link (nothing sent)",
        "description": "As Copy link: the link to share yourself, with nothing emailed or texted. A draft's link doesn't open, so a draft comes out of draft first (status sent). A voided contract answers 409.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contract_id",
            "in": "path",
            "required": true,
            "description": "Contract id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "allow_blanks": {
                    "type": "boolean",
                    "description": "Let it go out with {{blanks}} left for the signer to fill on the signing page. Default false: 409 with the blanks."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sign_url": "https://app.acme.com/sign/abc123",
                    "was_draft": true,
                    "contract": {
                      "id": "uuid",
                      "status": "sent",
                      "stage": "sent"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/contracts/{contract_id}/send": {
      "post": {
        "operationId": "send_contract",
        "tags": [
          "Contracts"
        ],
        "summary": "Send a contract for signature",
        "description": "Emails and / or texts the contract's lead the signing link (in the business's name, from its own email and number, as the key's person; billed like any text or email; opted-out leads aren't sent to), and the message shows in the lead's conversation.\n\n- A draft or declined contract becomes sent; sending again re-sends the same link.\n- `sent_via` lists what went, failures why a channel didn't.\n- Signed or voided contracts answer 409; one with no lead too.\n\nRequired scope: `leads:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contract_id",
            "in": "path",
            "required": true,
            "description": "Contract id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "description": "Default email.",
                    "enum": [
                      "email",
                      "sms",
                      "both"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "description": "A short note with the link (max 1000)."
                  },
                  "allow_blanks": {
                    "type": "boolean",
                    "description": "Let it go out with {{blanks}} left for the signer to fill on the signing page. Default false: 409 with the blanks."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "channel": "both",
                "note": "Here's the agreement we talked about."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sent_via": [
                      "email",
                      "text"
                    ],
                    "failures": [],
                    "sign_url": "https://app.acme.com/sign/abc123",
                    "contract": {
                      "id": "uuid",
                      "status": "sent",
                      "stage": "sent",
                      "send_count": 1
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/contracts/{contract_id}/void": {
      "post": {
        "operationId": "void_contract",
        "tags": [
          "Contracts"
        ],
        "summary": "Void a contract",
        "description": "As Void on the page: the signing link stops working right away. No undo; signed contracts can't be voided.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contract_id",
            "in": "path",
            "required": true,
            "description": "Contract id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/proposals": {
      "get": {
        "operationId": "list_proposals",
        "tags": [
          "Proposals"
        ],
        "summary": "Proposals",
        "description": "Newest first: your agency's own proposals (leave `workspace_id` out), or a sub-account's.\n\n- Who each is for, status (draft, sent, accepted, declined) and stage as the page shows it (draft, sent, viewed, accepted, declined, expired), when it was sent and opened, the package and add-ons the client said yes to (`accepted_choice`) and the contract that made, whether the AI is working on it (`ai_status` building or editing), `public_url` once it is out of draft, and page: where it opens in the app.\n- template=true lists your templates instead.\n- Credits spent (`credits_used`) only on your agency's own.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": false,
            "description": "A sub-account's proposals. Leave it out for your agency's own (a key restricted to one sub-account is always in its own).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "sent",
                "accepted",
                "declined"
              ]
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "A sub-account's: one lead's proposals.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "template",
            "in": "query",
            "required": false,
            "description": "true: your templates. Default false.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "next_before from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "scope": "agency",
                    "proposals": [
                      {
                        "id": "uuid",
                        "workspace_id": null,
                        "lead_id": null,
                        "title": "Proposal for Acme Dental",
                        "status": "sent",
                        "stage": "viewed",
                        "is_template": false,
                        "client_name": "Dana Lee",
                        "client_company": "Acme Dental",
                        "client_email": "dana@acmedental.com",
                        "client_phone": null,
                        "client_website": "acmedental.com",
                        "sent_at": "2026-11-04T15:00:00Z",
                        "last_sent_at": "2026-11-04T15:00:00Z",
                        "send_count": 1,
                        "viewed_at": "2026-11-04T15:12:00Z",
                        "last_viewed_at": "2026-11-04T15:40:00Z",
                        "view_count": 3,
                        "accepted_at": null,
                        "accepted_name": null,
                        "accepted_choice": null,
                        "declined_at": null,
                        "decline_reason": null,
                        "expires_at": null,
                        "contract_id": null,
                        "contract_template_id": "uuid",
                        "signup_link_id": "uuid",
                        "booking_calendar_id": null,
                        "accept_label": null,
                        "source_proposal_id": null,
                        "created_by": "uuid",
                        "created_at": "2026-11-04T14:40:00Z",
                        "updated_at": "2026-11-04T15:00:00Z",
                        "ai_status": "idle",
                        "public_url": "https://app.youragency.com/proposal/9f2c...",
                        "page": "/agency/proposals?p=uuid",
                        "credits_used": 4.2
                      }
                    ],
                    "has_more": false,
                    "next_before": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_proposal",
        "tags": [
          "Proposals"
        ],
        "summary": "Create a proposal (the AI writes it, or your own HTML)",
        "description": "As New proposal, one of three ways.\n\n- build: the AI writes and designs the whole proposal from your brief and prices, as Build with AI does, and makes its pictures (images, 0-24); it answers 201 at once with `ai.message_id` while the AI works for a minute or two: read the proposal until `ai_status` is idle.\n- It never invents results, testimonials, clients or prices: what it doesn't know is left as [blanks].\n- `template_id`: a copy of one of your templates (`GET /v1/proposals?template=true`) for the client you name: a template that uses `{{variables}}` is filled in, any other is rewritten by the AI (rewrite: true or false decides).\n- doc: your own design, no AI and no credits: `{ theme, css, sections }`, where a custom section is your HTML and CSS (layout fullWidth or contained), css is the Brand CSS every custom section shares, and built-in sections (pricing for the packages they pick from) can sit beside them; `as_template`: true saves it straight as a template.\n- The answer lists warnings for anything the page leaves out (no scripts, forms or iframes; https pictures; CSS that loads only Google Fonts and https files).\n- Rules and an example: `GET /v1/proposals/design-guide`.\n- AI work spends credits: about 1.5-3.5 for the writing plus 0.5 a picture, a change about 0.3-1.5 (in a sub-account, at its own price for Proposals, often included); 402 when they don't cover it (nothing is made).\n- The next step after the client's \"I agree\": `contract_template_id` (the contract to sign), then `signup_link_id` (your agency's onboarding) or `booking_calendar_id` (a sub-account's booking page).\n- Nothing is sent.\n\nRequired scope: `leads:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "A sub-account's proposal. Leave it out for your agency's own (a key restricted to one sub-account is always in its own)."
                  },
                  "build": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The AI writes it: { brief (what you're proposing, who it's for, 10-8000 characters), pricing (your packages and prices in your words, max 3000), images (AI pictures 0-24, default 4), preset (auto = your brand colours, or a look: executive, editorial, mono, emerald, electric, sunset, ocean, blush, slate, noir, citrus, atelier) }. Or template_id."
                  },
                  "template_id": {
                    "type": "string",
                    "description": "Instead of build: a copy of this template."
                  },
                  "rewrite": {
                    "type": "boolean",
                    "description": "With template_id: the AI rewrites the copy for the client named. Default true, or false when the template uses {{variables}} (they fill in)."
                  },
                  "doc": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Instead of build: your own design, no AI. { theme: { headingFont, bodyFont, colors: { bg, surface, ink, muted, primary, accent }, radius, texture, numbered }, css: your Brand CSS (shared by every custom section, max 60,000), sections: [{ type: \"custom\", layout: \"fullWidth\" | \"contained\", html (max 100,000), css (max 50,000) }, or any built-in section: cover, letter, cards, feature, scope, timeline, stats, case_study, pricing, team, testimonial, faq, gallery, text, cta] } (1-40 sections). See GET /v1/proposals/design-guide."
                  },
                  "as_template": {
                    "type": "boolean",
                    "description": "With doc: save it as a template (no client). Make proposals from it with template_id."
                  },
                  "title": {
                    "type": "string",
                    "description": "Your name for it (max 200). Default: Proposal for <company or name>."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "A sub-account's lead it is for: fills in the client's name, email and phone, and its answer lands on the lead's timeline."
                  },
                  "client_name": {
                    "type": "string",
                    "description": "The client's name (max 200)."
                  },
                  "client_company": {
                    "type": "string",
                    "description": "Their company (max 200)."
                  },
                  "client_email": {
                    "type": "string",
                    "description": "Where it is emailed."
                  },
                  "client_phone": {
                    "type": "string",
                    "description": "Their phone."
                  },
                  "client_website": {
                    "type": "string",
                    "description": "Their website: a build reads it for context (it never quotes it word for word)."
                  },
                  "contract_template_id": {
                    "type": "string",
                    "description": "After I agree: this contract to sign (one of the same account's contract templates)."
                  },
                  "signup_link_id": {
                    "type": "string",
                    "description": "Agency proposals: after I agree (and the contract), this signup link (GET /v1/signup-links)."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "A sub-account's proposals: after I agree (and the contract), this booking page (GET /v1/calendars)."
                  },
                  "accept_label": {
                    "type": "string",
                    "description": "The accept button's words (max 60). Default I agree."
                  },
                  "expires_in_days": {
                    "type": "number",
                    "description": "The offer ends after this many days (1-365): the page still opens, but it can no longer be accepted."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "client_company": "Acme Dental",
                "client_name": "Dana Lee",
                "client_email": "dana@acmedental.com",
                "build": {
                  "brief": "Local SEO and Google Ads for a two-location dental clinic that wants more implant patients",
                  "pricing": "Growth $1,500/month, Scale $2,800/month; setup $500 once",
                  "images": 4
                },
                "contract_template_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "proposal": {
                      "id": "uuid",
                      "workspace_id": null,
                      "lead_id": null,
                      "title": "Proposal for Acme Dental",
                      "status": "draft",
                      "stage": "draft",
                      "is_template": false,
                      "client_name": "Dana Lee",
                      "client_company": "Acme Dental",
                      "client_email": "dana@acmedental.com",
                      "client_phone": null,
                      "client_website": "acmedental.com",
                      "sent_at": null,
                      "last_sent_at": "2026-11-04T15:00:00Z",
                      "send_count": 1,
                      "viewed_at": "2026-11-04T15:12:00Z",
                      "last_viewed_at": "2026-11-04T15:40:00Z",
                      "view_count": 0,
                      "accepted_at": null,
                      "accepted_name": null,
                      "accepted_choice": null,
                      "declined_at": null,
                      "decline_reason": null,
                      "expires_at": null,
                      "contract_id": null,
                      "contract_template_id": "uuid",
                      "signup_link_id": "uuid",
                      "booking_calendar_id": null,
                      "accept_label": null,
                      "source_proposal_id": null,
                      "created_by": "uuid",
                      "created_at": "2026-11-04T14:40:00Z",
                      "updated_at": "2026-11-04T15:00:00Z",
                      "ai_status": "building",
                      "public_url": null,
                      "page": "/agency/proposals?p=uuid",
                      "credits_used": 4.2
                    },
                    "ai": {
                      "started": true,
                      "message_id": "uuid",
                      "kind": "build"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/proposals/{proposal_id}": {
      "get": {
        "operationId": "get_proposal",
        "tags": [
          "Proposals"
        ],
        "summary": "One proposal",
        "description": "include=doc adds the whole document (theme, Brand CSS, every section with its custom HTML) and its rev, to change it with PATCH.\n\nAdds what it says:\n- its sections in order (type and heading; a custom section's layout and HTML length)\n- its words as plain text\n- the pricing (packages, add-ons, and whether the client picks one)\n- the [blanks] the AI left for what it didn't know\n- the `{{variables}}` it uses and the ones it has nothing to fill with\n- its pictures (ready, being made, failed)\n- the brief it was written from\n- the AI's last turn (working with its progress, or done with its reply and the changes it made) and its history (sent with how, viewed, accepted with the choice, declined)\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "proposal_id",
            "in": "path",
            "required": true,
            "description": "Proposal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "doc: the whole document as well (theme, css, sections).",
            "schema": {
              "type": "string",
              "enum": [
                "doc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "proposal": {
                      "id": "uuid",
                      "workspace_id": null,
                      "lead_id": null,
                      "title": "Proposal for Acme Dental",
                      "status": "sent",
                      "stage": "viewed",
                      "is_template": false,
                      "client_name": "Dana Lee",
                      "client_company": "Acme Dental",
                      "client_email": "dana@acmedental.com",
                      "client_phone": null,
                      "client_website": "acmedental.com",
                      "sent_at": "2026-11-04T15:00:00Z",
                      "last_sent_at": "2026-11-04T15:00:00Z",
                      "send_count": 1,
                      "viewed_at": "2026-11-04T15:12:00Z",
                      "last_viewed_at": "2026-11-04T15:40:00Z",
                      "view_count": 3,
                      "accepted_at": null,
                      "accepted_name": null,
                      "accepted_choice": null,
                      "declined_at": null,
                      "decline_reason": null,
                      "expires_at": null,
                      "contract_id": null,
                      "contract_template_id": "uuid",
                      "signup_link_id": "uuid",
                      "booking_calendar_id": null,
                      "accept_label": null,
                      "source_proposal_id": null,
                      "created_by": "uuid",
                      "created_at": "2026-11-04T14:40:00Z",
                      "updated_at": "2026-11-04T15:00:00Z",
                      "ai_status": "idle",
                      "public_url": "https://app.youragency.com/proposal/9f2c...",
                      "page": "/agency/proposals?p=uuid",
                      "credits_used": 4.2,
                      "sections": [
                        {
                          "id": "s1",
                          "type": "cover",
                          "heading": "Growing Acme Dental's new patients"
                        },
                        {
                          "id": "s4",
                          "type": "pricing",
                          "heading": "Investment"
                        }
                      ],
                      "text": "Growing Acme Dental's new patients · ...",
                      "pricing": {
                        "packages": [
                          {
                            "id": "p1",
                            "name": "Growth",
                            "price": "$1,500",
                            "period": "/month",
                            "features": [
                              "Local SEO",
                              "Google Ads"
                            ]
                          }
                        ],
                        "addons": [],
                        "client_picks": true
                      },
                      "blanks": [
                        "[Add a client result]"
                      ],
                      "variables": {
                        "used": [
                          "client_company"
                        ],
                        "unfilled": []
                      },
                      "images": {
                        "ready": 4,
                        "being_made": 0,
                        "failed": 0
                      },
                      "ai_last_turn": {
                        "id": "uuid",
                        "kind": "build",
                        "status": "done",
                        "progress": null,
                        "reply": "Your proposal is ready.",
                        "changes": [],
                        "started_at": "2026-11-04T14:40:00Z",
                        "finished_at": "2026-11-04T14:42:10Z"
                      },
                      "events": [
                        {
                          "id": "uuid",
                          "event": "sent",
                          "actor_user_id": "uuid",
                          "details": {
                            "to": "dana@acmedental.com"
                          },
                          "created_at": "2026-11-04T15:00:00Z"
                        }
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_proposal",
        "tags": [
          "Proposals"
        ],
        "summary": "Change it yourself (your own HTML, no AI)",
        "description": "Your own changes, saved at once with no AI and no credits (an editor open on it picks them up).\n\n- doc replaces the whole document; or theme (merged into the current one), css (the Brand CSS; \"\" removes it), sections (the whole list) and ops: changes by section id (`GET /v1/proposals/{proposal_id}` lists them), { op: \"update\", id, set: `{ html, css, heading, ... }` }, `{ op: \"replace\", id, section }`, `{ op: \"add\", after: id | \"start\", section }`, `{ op: \"remove\", id }`, `{ op: \"move\", id, after }`, `{ op: \"theme\", set }`, `{ op: \"css\", css }`.\n- Also its name, the client (not on a template), the button's words, the end date and the next step.\n- The answer lists the changes made and warnings for anything the page leaves out.\n- An accepted proposal answers 409 (duplicate it), as does one the AI is working on, or one changed meanwhile.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "proposal_id",
            "in": "path",
            "required": true,
            "description": "Proposal id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "A sub-account's proposal. Leave it out for your agency's own (a key restricted to one sub-account is always in its own)."
                  },
                  "title": {
                    "type": "string",
                    "description": "Its name (max 200)."
                  },
                  "doc": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The whole document: { theme, css, sections } (as in POST /v1/proposals)."
                  },
                  "theme": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Theme fields to change."
                  },
                  "css": {
                    "type": "string",
                    "description": "The Brand CSS every custom section shares. \"\" removes it."
                  },
                  "sections": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The whole list of sections."
                  },
                  "ops": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Changes by section id (up to 60): update, replace, add, remove, move, theme, css."
                  },
                  "client_name": {
                    "type": "string",
                    "description": "The client's name (max 200)."
                  },
                  "client_company": {
                    "type": "string",
                    "description": "Their company (max 200)."
                  },
                  "client_email": {
                    "type": "string",
                    "description": "Where it is emailed."
                  },
                  "client_phone": {
                    "type": "string",
                    "description": "Their phone."
                  },
                  "client_website": {
                    "type": "string",
                    "description": "Their website: a build reads it for context (it never quotes it word for word)."
                  },
                  "accept_label": {
                    "type": "string",
                    "description": "The accept button's words (max 60); null for I agree."
                  },
                  "expires_in_days": {
                    "type": "number",
                    "description": "The offer ends this many days from now (1-365); null for no end."
                  },
                  "contract_template_id": {
                    "type": "string",
                    "description": "After I agree: this contract to sign; null for none."
                  },
                  "signup_link_id": {
                    "type": "string",
                    "description": "Agency proposals: after I agree, this signup link; null for none."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "A sub-account's proposals: after I agree, this booking page; null for none."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "ops": [
                  {
                    "op": "update",
                    "id": "hero",
                    "set": {
                      "html": "<header class=\"hero\"><h1>A plan for {{client_company}}</h1></header>"
                    }
                  }
                ],
                "css": ".hero{padding:120px 8vw;background:var(--pp-primary);color:var(--pp-on-primary)}"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "proposal": {
                      "id": "uuid",
                      "title": "Proposal for Acme Dental",
                      "status": "draft",
                      "stage": "draft"
                    },
                    "changes": [
                      "Changed the Brand CSS",
                      "Updated \"custom\""
                    ],
                    "sections": [
                      {
                        "id": "hero",
                        "type": "custom",
                        "heading": null,
                        "layout": "fullWidth",
                        "html_length": 84
                      },
                      {
                        "id": "s4",
                        "type": "pricing",
                        "heading": "Investment"
                      }
                    ],
                    "variables": {
                      "used": [
                        "client_company"
                      ],
                      "unfilled": []
                    },
                    "warnings": []
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/proposals/design-guide": {
      "get": {
        "operationId": "proposal_design_guide",
        "tags": [
          "Proposals"
        ],
        "summary": "How to design one in your own HTML",
        "description": "The rules for a proposal in your own HTML and CSS, as markdown an AI can read before it designs one: the document's parts, custom sections and the Brand CSS, what HTML and CSS are drawn (no JavaScript; https pictures; Google Fonts), the theme's CSS variables, the `{{variables}}`, pricing and the I agree block, templates, and an example.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "guide": "# Proposals in your own HTML and CSS\n\nA proposal is a document: { theme, css, sections } ...",
                    "format": "markdown"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/proposals/{proposal_id}/edit": {
      "post": {
        "operationId": "edit_proposal",
        "tags": [
          "Proposals"
        ],
        "summary": "Change it with the AI",
        "description": "One change from the editor's AI Designer, in your words: \"make the pricing a table\", \"add an FAQ about contracts\", \"shorter, and warmer\".\n\n- Answers at once with `ai.message_id` while the AI works; read the proposal for its reply and the changes it made.\n- Spends credits; an accepted proposal answers 409 (duplicate it), as does one the AI is still working on.\n\nRequired scope: `leads:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "proposal_id",
            "in": "path",
            "required": true,
            "description": "Proposal id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instruction": {
                    "type": "string",
                    "description": "What to change (max 4000)."
                  },
                  "section_id": {
                    "type": "string",
                    "description": "The section it's about (GET /v1/proposals/{proposal_id} lists them)."
                  }
                },
                "required": [
                  "instruction"
                ],
                "additionalProperties": true
              },
              "example": {
                "instruction": "Add a short FAQ about the 3-month minimum and make the pricing a table."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "proposal": {
                      "id": "uuid",
                      "ai_status": "editing"
                    },
                    "ai": {
                      "started": true,
                      "message_id": "uuid",
                      "kind": "edit"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/proposals/{proposal_id}/link": {
      "post": {
        "operationId": "get_proposal_link",
        "tags": [
          "Proposals"
        ],
        "summary": "Get the public link (nothing sent)",
        "description": "As Copy link: the link to share yourself, with nothing emailed or texted. A draft's page doesn't open, so a draft comes out of draft first (status sent). A template answers 409.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "proposal_id",
            "in": "path",
            "required": true,
            "description": "Proposal id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "allow_blanks": {
                    "type": "boolean",
                    "description": "Let it go out with [blanks] the AI left for what it didn't know. Default false: 409 with the blanks."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "public_url": "https://app.youragency.com/proposal/9f2c...",
                    "was_draft": true,
                    "proposal": {
                      "id": "uuid",
                      "status": "sent",
                      "stage": "sent"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/proposals/{proposal_id}/send": {
      "post": {
        "operationId": "send_proposal",
        "tags": [
          "Proposals"
        ],
        "summary": "Send a proposal",
        "description": "Emails the client the link in your brand (a sub-account's: the business's), with your note.\n\n- A sub-account's proposal to one of its leads goes through the lead's conversation as the key's person, by email and / or text (billed like any text or email; opted-out leads aren't sent to).\n- A draft or declined proposal becomes sent; sending again re-sends the same link.\n- `sent_via` lists what went, failures why a channel didn't.\n- An accepted proposal or a template answers 409.\n\nRequired scope: `leads:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "proposal_id",
            "in": "path",
            "required": true,
            "description": "Proposal id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "description": "Default email. sms and both: a sub-account's proposal to a lead.",
                    "enum": [
                      "email",
                      "sms",
                      "both"
                    ]
                  },
                  "to_email": {
                    "type": "string",
                    "description": "Default: the client's email (or the lead's)."
                  },
                  "note": {
                    "type": "string",
                    "description": "Your words in the email instead of the standard ones (max 1500)."
                  },
                  "allow_blanks": {
                    "type": "boolean",
                    "description": "Let it go out with [blanks] the AI left for what it didn't know. Default false: 409 with the blanks."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "note": "Dana, here's the plan we talked about. Happy to walk you through it on Thursday."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sent_via": [
                      "email"
                    ],
                    "failures": [],
                    "public_url": "https://app.youragency.com/proposal/9f2c...",
                    "proposal": {
                      "id": "uuid",
                      "status": "sent",
                      "stage": "sent",
                      "send_count": 1
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/proposals/{proposal_id}/duplicate": {
      "post": {
        "operationId": "duplicate_proposal",
        "tags": [
          "Proposals"
        ],
        "summary": "Duplicate, save as a template, or use for another client",
        "description": "A copy with the same design and words and a new link, nothing sent or answered (an accepted proposal too: that's how a new version is made).\n\n- `as_template` saves it as a template.\n- Naming a client or a lead makes it theirs and the AI rewrites it for them, keeping the design and prices (Use for another client; rewrite: false keeps the words; the rewrite spends credits).\n- It stays in its account.\n\nRequired scope: `leads:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "proposal_id",
            "in": "path",
            "required": true,
            "description": "Proposal id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "as_template": {
                    "type": "boolean",
                    "description": "Save the copy as a template (no client)."
                  },
                  "title": {
                    "type": "string",
                    "description": "The copy's name (max 200)."
                  },
                  "lead_id": {
                    "type": "string",
                    "description": "A sub-account's lead it is for: fills in the client's name, email and phone, and its answer lands on the lead's timeline."
                  },
                  "client_name": {
                    "type": "string",
                    "description": "The client's name (max 200)."
                  },
                  "client_company": {
                    "type": "string",
                    "description": "Their company (max 200)."
                  },
                  "client_email": {
                    "type": "string",
                    "description": "Where it is emailed."
                  },
                  "client_phone": {
                    "type": "string",
                    "description": "Their phone."
                  },
                  "client_website": {
                    "type": "string",
                    "description": "Their website: a build reads it for context (it never quotes it word for word)."
                  },
                  "rewrite": {
                    "type": "boolean",
                    "description": "For a client: the AI rewrites it for them. Default true."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "client_company": "Brightside Ortho",
                "client_name": "Sam Ortiz",
                "client_email": "sam@brightside.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "proposal": {
                      "id": "uuid",
                      "title": "Proposal for Brightside Ortho",
                      "status": "draft",
                      "stage": "draft",
                      "source_proposal_id": "uuid"
                    },
                    "ai": {
                      "started": true,
                      "message_id": "uuid",
                      "kind": "retarget"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/sales": {
      "get": {
        "operationId": "get_sales",
        "tags": [
          "Dashboard"
        ],
        "summary": "The Sales page: won jobs, parts, tips and profit",
        "description": "Settings > Features > Sales (off until an owner or admin turns it on: 403 `feature_off` until then).\n\n- Won jobs in the window by the date they were won, as the Sales page adds them up: what customers paid, parts, tips and profit in total, per technician (`deal_sold_by`, else whoever the lead is assigned to), per lead source and per tag, plus the jobs themselves.\n- Every group also has plans, `monthly_cents` (the monthly revenue its new plans add) and `expected_cents` (what its jobs are expected to bring in, one-time jobs at their amount), and each job its `deal_type` and plan (Plans & memberships).\n- Record a sale with `PATCH /v1/leads/{lead_id}:` status won, `deal_value_cents`, `deal_parts_cents`, `deal_tip_cents`, `deal_sold_by`.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "1-365, default 30.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO start, instead of days.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO end, default now.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights": {
      "get": {
        "operationId": "get_ad_insights",
        "tags": [
          "Ads & Google"
        ],
        "summary": "The sub-account's Ad Insights",
        "description": "Exactly what its Ad Insights page shows: spend, leads, cost per lead, impressions and clicks for the Meta ad accounts attached to it (one, or all of them added up with each account's share in accounts, and an error for one that couldn't be read), each read with whichever connected Facebook profile can; per campaign and per ad, only the campaigns and ads the agency picked for this sub-account; ads left out (`ads_hidden`) when the agency hides them from the client.\n\n- Amounts are added up in each account's own currency (`accounts_meta`).\n- 403 `ad_insights_off` when Ad Insights is off for it.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ad_account_id",
            "in": "query",
            "required": false,
            "description": "\"all\" (default) or one attached account, act_123.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_preset",
            "in": "query",
            "required": false,
            "description": "Default last_30d.",
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_14d",
                "last_30d",
                "last_90d",
                "this_month",
                "last_month",
                "maximum"
              ]
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD, with until (instead of date_preset).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "query",
            "required": false,
            "description": "Only this campaign's ads.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "summary": {
                      "total_spend": 1240.5,
                      "total_leads": 62,
                      "avg_cost_per_lead": 20.01,
                      "total_impressions": 88120,
                      "total_clicks": 1904
                    },
                    "campaigns": [
                      {
                        "id": "120210000000",
                        "name": "Roof leads - Dallas",
                        "effective_status": "ACTIVE",
                        "spend": 820.1,
                        "leads": 44,
                        "impressions": 60110,
                        "clicks": 1302
                      }
                    ],
                    "ads": [],
                    "account_id": "all",
                    "account_ids": [
                      "act_123",
                      "act_456"
                    ],
                    "accounts_meta": {
                      "act_123": {
                        "name": "Acme Roofing",
                        "currency": "USD"
                      }
                    },
                    "accounts": [
                      {
                        "id": "act_123",
                        "total_spend": 820.1,
                        "total_leads": 44,
                        "campaigns": 3,
                        "running": 2,
                        "daily_budget": 40
                      }
                    ],
                    "window": {
                      "date_preset": "last_30d"
                    },
                    "filtered": true,
                    "ads_hidden": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads": {
      "get": {
        "operationId": "google_ads_status",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Ads: the connection and conversions sent",
        "description": "The sub-account's own Google Ads connection (Ad Insights > Google Ads): its ad accounts (customers), the one in use, whether booked / won leads are sent back as conversions and to which conversion actions, and the newest conversions with their status (pending, sent, failed, skipped) and how each lead was matched (gclid, gbraid, wbraid or email / phone).\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-ads/report": {
      "get": {
        "operationId": "google_ads_report",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Ads reports, live",
        "description": "One of the Google Ads screens, read live from Google for one of the sub-account's ad accounts: overview (campaigns with spend, clicks, conversions, totals and by day), `ad_groups`, keywords, ads, `search_terms`, negatives, `campaign_settings` (`campaign_id`), `conversion_actions`, bidding, recommendations. Nothing is changed.\n\nWho can call it: Owners and admins.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report",
            "in": "query",
            "required": false,
            "description": "Default overview.",
            "schema": {
              "type": "string",
              "enum": [
                "overview",
                "ad_groups",
                "keywords",
                "ads",
                "search_terms",
                "negatives",
                "campaign_settings",
                "conversion_actions",
                "bidding",
                "recommendations"
              ]
            }
          },
          {
            "name": "range",
            "in": "query",
            "required": false,
            "description": "Default last_30d.",
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "last_7d",
                "last_14d",
                "last_30d",
                "last_90d"
              ]
            }
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "One of its accounts (GET /v1/google-ads). Default: the one picked in the app.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "query",
            "required": false,
            "description": "Narrow to one campaign.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ad_group_id",
            "in": "query",
            "required": false,
            "description": "Narrow to one ad group.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "search_terms: rows, default 500.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/profiles": {
      "get": {
        "operationId": "list_gbp_profiles",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Business Profiles",
        "description": "Every Business Profile connected to the sub-account (it can have several): the location, rating, review count, whether Google's API answers for it, and its auto-reply, auto-post and photo settings, local knowledge, words for replies and photo geotag spot; plus the Google logins connected (email only).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/reviews": {
      "get": {
        "operationId": "list_gbp_reviews",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google reviews and replies",
        "description": "Reviews synced from Google every 15 minutes, newest first, with the reply sent, the draft waiting for approval and its status.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One profile.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "draft",
                "sending",
                "sent",
                "skipped",
                "failed"
              ]
            }
          },
          {
            "name": "unanswered",
            "in": "query",
            "required": false,
            "description": "Only reviews without a reply.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "max_stars",
            "in": "query",
            "required": false,
            "description": "This many stars or fewer.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/posts": {
      "get": {
        "operationId": "list_gbp_posts",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Business Profile posts",
        "description": "Drafts, scheduled and published posts (title, text, button, offer, photo, when, the live link).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One profile.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "scheduled",
                "publishing",
                "published",
                "failed"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_gbp_post",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Create a Google post",
        "description": "A post in your own words, Google's rules checked first. Saved as a draft waiting for an OK, or approved at once with approve: true (it then goes up publicly on the business's Google profile on `scheduled_for`, on its own when the profile is connected to Google; otherwise the app shows it to copy).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its profiles (default its first)."
                  },
                  "kind": {
                    "type": "string",
                    "description": "STANDARD (an update, default), OFFER or EVENT.",
                    "enum": [
                      "STANDARD",
                      "OFFER",
                      "EVENT"
                    ]
                  },
                  "title": {
                    "type": "string",
                    "description": "OFFER and EVENT posts: up to 58 characters."
                  },
                  "body": {
                    "type": "string",
                    "description": "The post, up to 1,500 characters. Google refuses a phone number in the text: use the CALL button."
                  },
                  "cta_type": {
                    "type": "string",
                    "description": "The button (not on OFFER posts). Left out: the profile's own button and link.",
                    "enum": [
                      "NONE",
                      "LEARN_MORE",
                      "BOOK",
                      "CALL",
                      "ORDER",
                      "SHOP",
                      "SIGN_UP"
                    ]
                  },
                  "cta_url": {
                    "type": "string",
                    "description": "Full https:// link for the button (or an offer's link)."
                  },
                  "coupon_code": {
                    "type": "string",
                    "description": "OFFER: the code, up to 58 characters."
                  },
                  "offer_terms": {
                    "type": "string",
                    "description": "OFFER: terms and conditions."
                  },
                  "starts_at": {
                    "type": "string",
                    "description": "EVENT: when it starts, ISO date-time."
                  },
                  "ends_at": {
                    "type": "string",
                    "description": "EVENT: when it ends; OFFER: when it ends (default 30 days). ISO."
                  },
                  "image_url": {
                    "type": "string",
                    "description": "A public link to a JPG or PNG (5 MB, 250 x 250 at least), copied in like an upload."
                  },
                  "scheduled_for": {
                    "type": "string",
                    "description": "When it goes up on Google, ISO date-time (default: the next posting day on the profile's schedule)."
                  },
                  "approve": {
                    "type": "boolean",
                    "description": "true: approved now (scheduled), as the app's Schedule it. Default false (a draft)."
                  }
                },
                "required": [
                  "workspace_id",
                  "body"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "body": "Spring tune-ups are open: book a visit and we'll check your whole system in under an hour.",
                "cta_type": "BOOK",
                "cta_url": "https://acmehvac.com/book"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "post": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "status": "draft",
                      "kind": "STANDARD",
                      "title": null,
                      "body": "Spring tune-ups are open: book a visit and we'll check your whole system in under an hour.",
                      "cta_type": "BOOK",
                      "cta_url": "https://acmehvac.com/book",
                      "coupon_code": null,
                      "offer_terms": null,
                      "starts_at": null,
                      "ends_at": null,
                      "image_url": null,
                      "scheduled_for": "2026-11-03T17:00:00Z",
                      "published_at": null,
                      "google_post_url": null,
                      "source": "user",
                      "error": null,
                      "created_at": "2026-10-29T15:00:00Z",
                      "updated_at": "2026-10-29T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/optimizer": {
      "get": {
        "operationId": "list_gbp_optimizer",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Profile Optimizer runs",
        "description": "Each Profile Optimizer check, newest first: the score, what it found, the keywords, its suggestions and the changes made from it (and undone).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One profile.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-25, default 5.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/map-rankings": {
      "get": {
        "operationId": "list_map_rankings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Map Rankings: keywords and scans",
        "description": "Where the business ranks on Google Maps across a grid around it: the keywords tracked (grid, schedule, next and last scan) and the scans, newest first, each with its summary (points, found, top 3, average rank).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyword_id",
            "in": "query",
            "required": false,
            "description": "One keyword's scans.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One profile.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/map-rankings/scans/{scan_id}": {
      "get": {
        "operationId": "get_rank_scan",
        "tags": [
          "Ads & Google"
        ],
        "summary": "One Map Rankings scan",
        "description": "Every grid point with its rank (null: not in the top 20), the competitors found, and the next steps to rank #1 once they've been written (they are written when the scan is first opened in the app).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "scan_id",
            "in": "path",
            "required": true,
            "description": "Scan id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/listings": {
      "get": {
        "operationId": "get_listings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Business Listings",
        "description": "The directories the business is being listed on: each one's status (queued, scanning, listed, mismatch, `not_listed`, working, `needs_you`, submitted, live, owner, skipped, failed) with counts, what differs or what's needed from the owner, the listing link, and the latest activity. Passwords and verification codes are never returned.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/posts/write": {
      "post": {
        "operationId": "write_gbp_posts",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Have the AI write Google posts",
        "description": "The AI writes 1-8 posts in the business's voice from an idea, or one post about each photo of the work in `photo_urls` (the post carries that photo), dated on the profile's posting days. They are saved as drafts: nothing goes to Google until one is approved or published.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its profiles (default its first)."
                  },
                  "idea": {
                    "type": "string",
                    "description": "What to write about, up to 600 characters (needed for OFFER and EVENT)."
                  },
                  "kind": {
                    "type": "string",
                    "description": "STANDARD (an update, default), OFFER or EVENT.",
                    "enum": [
                      "STANDARD",
                      "OFFER",
                      "EVENT"
                    ]
                  },
                  "count": {
                    "type": "number",
                    "description": "1-8, default 4 (with photo_urls: one per photo)."
                  },
                  "photo_urls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 8 public JPG or PNG links of the business's work."
                  },
                  "cta_type": {
                    "type": "string",
                    "description": "The button (not on OFFER posts). Left out: the profile's own button and link.",
                    "enum": [
                      "NONE",
                      "LEARN_MORE",
                      "BOOK",
                      "CALL",
                      "ORDER",
                      "SHOP",
                      "SIGN_UP"
                    ]
                  },
                  "cta_url": {
                    "type": "string",
                    "description": "Full https:// link for the button (or an offer's link)."
                  },
                  "starts_at": {
                    "type": "string",
                    "description": "EVENT: when it starts, ISO date-time."
                  },
                  "ends_at": {
                    "type": "string",
                    "description": "EVENT: when it ends; OFFER: when it ends (default 30 days). ISO."
                  },
                  "scheduled_for": {
                    "type": "string",
                    "description": "The date of a single post, ISO."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "idea": "Free furnace check with any tune-up this month",
                "count": 2
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "posts": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "profile_id": "uuid",
                        "status": "draft",
                        "kind": "STANDARD",
                        "title": null,
                        "body": "Spring tune-ups are open: book a visit and we'll check your whole system in under an hour.",
                        "cta_type": "BOOK",
                        "cta_url": "https://acmehvac.com/book",
                        "coupon_code": null,
                        "offer_terms": null,
                        "starts_at": null,
                        "ends_at": null,
                        "image_url": null,
                        "scheduled_for": "2026-11-03T17:00:00Z",
                        "published_at": null,
                        "google_post_url": null,
                        "source": "user",
                        "error": null,
                        "created_at": "2026-10-29T15:00:00Z",
                        "updated_at": "2026-10-29T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/posts/{post_id}": {
      "patch": {
        "operationId": "update_gbp_post",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Edit a Google post",
        "description": "Change a post that isn't on Google yet (draft, scheduled or failed): send only what changes; `image_url` null removes the photo. Google's rules are checked on the result. A scheduled post stays approved for its new date.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "post_id",
            "in": "path",
            "required": true,
            "description": "Post id (GET /v1/google-business/posts).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "OFFER and EVENT posts: up to 58 characters."
                  },
                  "body": {
                    "type": "string",
                    "description": "The post, up to 1,500 characters. Google refuses a phone number in the text: use the CALL button."
                  },
                  "cta_type": {
                    "type": "string",
                    "description": "The button (not on OFFER posts). Left out: the profile's own button and link.",
                    "enum": [
                      "NONE",
                      "LEARN_MORE",
                      "BOOK",
                      "CALL",
                      "ORDER",
                      "SHOP",
                      "SIGN_UP"
                    ]
                  },
                  "cta_url": {
                    "type": "string",
                    "description": "Full https:// link for the button (or an offer's link)."
                  },
                  "coupon_code": {
                    "type": "string",
                    "description": "OFFER: the code, up to 58 characters."
                  },
                  "offer_terms": {
                    "type": "string",
                    "description": "OFFER: terms and conditions."
                  },
                  "starts_at": {
                    "type": "string",
                    "description": "EVENT: when it starts, ISO date-time."
                  },
                  "ends_at": {
                    "type": "string",
                    "description": "EVENT: when it ends; OFFER: when it ends (default 30 days). ISO."
                  },
                  "scheduled_for": {
                    "type": "string",
                    "description": "When it goes up on Google, ISO date-time (default: the next posting day on the profile's schedule)."
                  },
                  "image_url": {
                    "type": "string",
                    "description": "A public JPG or PNG link, or null to remove the photo."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "body": "Spring tune-ups are open this week only.",
                "scheduled_for": "2026-11-04T17:00:00Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "post": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "status": "draft",
                      "kind": "STANDARD",
                      "title": null,
                      "body": "Spring tune-ups are open: book a visit and we'll check your whole system in under an hour.",
                      "cta_type": "BOOK",
                      "cta_url": "https://acmehvac.com/book",
                      "coupon_code": null,
                      "offer_terms": null,
                      "starts_at": null,
                      "ends_at": null,
                      "image_url": null,
                      "scheduled_for": "2026-11-03T17:00:00Z",
                      "published_at": null,
                      "google_post_url": null,
                      "source": "user",
                      "error": null,
                      "created_at": "2026-10-29T15:00:00Z",
                      "updated_at": "2026-10-29T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_gbp_post",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Delete a Google post",
        "description": "Removes the post from the app. A post already published stays on Google (`still_on_google`: true); remove it there. Not while it is going up.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "post_id",
            "in": "path",
            "required": true,
            "description": "Post id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid",
                    "still_on_google": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/posts/{post_id}/approve": {
      "post": {
        "operationId": "approve_gbp_post",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Approve a Google post",
        "description": "A draft becomes scheduled: it goes up publicly on the business's Google profile on its date (on its own when the profile is connected to Google). Google's rules are checked first and the date must not have passed (send `scheduled_for` to move it).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "post_id",
            "in": "path",
            "required": true,
            "description": "Post id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scheduled_for": {
                    "type": "string",
                    "description": "A new date, ISO (default the post's own)."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "post": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "status": "scheduled",
                      "kind": "STANDARD",
                      "title": null,
                      "body": "Spring tune-ups are open: book a visit and we'll check your whole system in under an hour.",
                      "cta_type": "BOOK",
                      "cta_url": "https://acmehvac.com/book",
                      "coupon_code": null,
                      "offer_terms": null,
                      "starts_at": null,
                      "ends_at": null,
                      "image_url": null,
                      "scheduled_for": "2026-11-03T17:00:00Z",
                      "published_at": null,
                      "google_post_url": null,
                      "source": "user",
                      "error": null,
                      "created_at": "2026-10-29T15:00:00Z",
                      "updated_at": "2026-10-29T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/posts/{post_id}/unschedule": {
      "post": {
        "operationId": "unschedule_gbp_post",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Unschedule a Google post",
        "description": "A scheduled post goes back to the drafts, so it doesn't go up on its date.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "post_id",
            "in": "path",
            "required": true,
            "description": "Post id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "post": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "status": "draft",
                      "kind": "STANDARD",
                      "title": null,
                      "body": "Spring tune-ups are open: book a visit and we'll check your whole system in under an hour.",
                      "cta_type": "BOOK",
                      "cta_url": "https://acmehvac.com/book",
                      "coupon_code": null,
                      "offer_terms": null,
                      "starts_at": null,
                      "ends_at": null,
                      "image_url": null,
                      "scheduled_for": "2026-11-03T17:00:00Z",
                      "published_at": null,
                      "google_post_url": null,
                      "source": "user",
                      "error": null,
                      "created_at": "2026-10-29T15:00:00Z",
                      "updated_at": "2026-10-29T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/posts/{post_id}/publish": {
      "post": {
        "operationId": "publish_gbp_post",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Post on Google now",
        "description": "Publishes the post publicly on the business's Google profile right away, as the app's Post now (a draft, scheduled or failed post).\n\n- It needs the profile connected to Google; Google's rules are checked first.\n- When Google doesn't take it the answer is 409 with `details.code`: `awaiting_google` (Google hasn't opened its API to the account yet) or `not_posted` (the reason is in error and on the post).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "post_id",
            "in": "path",
            "required": true,
            "description": "Post id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "post": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "status": "published",
                      "kind": "STANDARD",
                      "title": null,
                      "body": "Spring tune-ups are open: book a visit and we'll check your whole system in under an hour.",
                      "cta_type": "BOOK",
                      "cta_url": "https://acmehvac.com/book",
                      "coupon_code": null,
                      "offer_terms": null,
                      "starts_at": null,
                      "ends_at": null,
                      "image_url": null,
                      "scheduled_for": "2026-11-03T17:00:00Z",
                      "published_at": "2026-10-29T15:02:11Z",
                      "google_post_url": "https://local.google.com/place?id=123&use=posts&lpsid=456",
                      "source": "user",
                      "error": null,
                      "created_at": "2026-10-29T15:00:00Z",
                      "updated_at": "2026-10-29T15:00:00Z"
                    },
                    "url": "https://local.google.com/place?id=123&use=posts&lpsid=456"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/reviews/{review_id}/draft": {
      "post": {
        "operationId": "draft_gbp_reply",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Have the AI draft a review reply",
        "description": "The AI writes the reply in the business's voice and tone (the tool's reply settings), or rewrites it following instruction, and saves it as the review's draft. Nothing is posted.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "review_id",
            "in": "path",
            "required": true,
            "description": "Review id (GET /v1/google-business/reviews).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instruction": {
                    "type": "string",
                    "description": "How to write or change it, up to 600 characters (e.g. mention the warranty)."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "review": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "source": "api",
                      "reviewer_name": "Dana R.",
                      "star_rating": 5,
                      "comment": "Fast and friendly.",
                      "reply_text": null,
                      "draft_reply": "Thank you, Dana! It was a pleasure.",
                      "status": "draft",
                      "sent_by": null,
                      "error": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/reviews/{review_id}": {
      "patch": {
        "operationId": "update_gbp_review",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Edit a reply draft, or skip a review",
        "description": "`draft_reply` replaces the saved draft (nothing is posted); skip: true takes the review off the list to answer, false brings it back.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "review_id",
            "in": "path",
            "required": true,
            "description": "Review id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "draft_reply": {
                    "type": "string",
                    "description": "The reply draft, up to 4,000 characters."
                  },
                  "skip": {
                    "type": "boolean",
                    "description": "true skips the review; false brings it back."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "draft_reply": "Thank you, Dana! We're glad the new furnace is keeping you warm."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "review": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "source": "api",
                      "reviewer_name": "Dana R.",
                      "star_rating": 5,
                      "comment": "Fast and friendly.",
                      "reply_text": null,
                      "draft_reply": "Thank you, Dana! It was a pleasure.",
                      "status": "draft",
                      "sent_by": null,
                      "error": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/reviews/{review_id}/reply": {
      "post": {
        "operationId": "reply_gbp_review",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Reply to a Google review",
        "description": "Posts text (or the saved draft) as the business's public reply under the review on Google, as the app's Post reply; on a review already answered it replaces the reply. Only reviews that came from Google with the profile connected: one read from Google Maps or pasted in answers 409 `copy_by_hand` (paste the reply on Google yourself); `awaiting_google` and `not_posted` as for posts.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "review_id",
            "in": "path",
            "required": true,
            "description": "Review id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "The reply, up to 4,000 characters (default: the saved draft)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "text": "Thank you, Dana! We're glad the new furnace is keeping you warm."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "review": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "source": "api",
                      "reviewer_name": "Dana R.",
                      "star_rating": 5,
                      "comment": "Fast and friendly.",
                      "reply_text": "Thank you, Dana! We're glad the new furnace is keeping you warm.",
                      "draft_reply": "Thank you, Dana! It was a pleasure.",
                      "status": "sent",
                      "sent_by": "user",
                      "error": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/optimizer/apply": {
      "post": {
        "operationId": "apply_gbp_optimizer",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Apply Profile Optimizer suggestions",
        "description": "Makes the picked suggestions of a Profile Optimizer check (the newest, or `run_id`) on the business's live Google profile, which everyone sees: categories added, a new description, services, attributes turned on, the Book button linked to one of its calendars, holiday hours, the website link (`website_link`) and the opening date.\n\n- Ids come from the run's suggestions (`GET /v1/google-business/optimizer`).\n- Each change is recorded and can be undone; `dry_run`: true asks Google to check them without changing anything.\n- results says what worked.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its profiles (default its first)."
                  },
                  "run_id": {
                    "type": "string",
                    "description": "The check (default the newest)."
                  },
                  "categories": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Category ids to add (suggestions.categories[].id)."
                  },
                  "description": {
                    "type": "string",
                    "description": "The description to use, 50-750 characters (the suggested one, edited or not)."
                  },
                  "services": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Service ids (suggestions.services[].id)."
                  },
                  "service_updates": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Better descriptions for services already on the profile (suggestions.serviceUpdates[].id). Only those change; every other service goes back as Google has it, and a service edited on Google since the check is left out."
                  },
                  "attributes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Attribute ids to turn on (suggestions.attributes[].id)."
                  },
                  "booking_calendar_id": {
                    "type": "string",
                    "description": "The calendar the Book button opens (suggestions.booking.calendars[].id)."
                  },
                  "holidays": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ key, closed }] from suggestions.holidays (closed defaults to true)."
                  },
                  "website_link": {
                    "type": "boolean",
                    "description": "true: put suggestions.websiteLink.url on the profile (tracking tags on the website link, or the business's site when the profile has none)."
                  },
                  "opening_date": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ year, month }: when the business opened, when suggestions.openingDate asks for it."
                  },
                  "dry_run": {
                    "type": "boolean",
                    "description": "true: Google validates, nothing changes."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "categories": [
                  "categories/gcid:hvac_contractor"
                ],
                "attributes": [
                  "attributes/has_onsite_services"
                ],
                "dry_run": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "dry_run": true,
                    "results": [
                      {
                        "key": "categories",
                        "ok": true,
                        "validated": true,
                        "message": null
                      },
                      {
                        "key": "attributes",
                        "ok": true,
                        "validated": true,
                        "message": "Not sent in a test run."
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/optimizer/changes/{change_id}/undo": {
      "post": {
        "operationId": "undo_gbp_optimizer_change",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Undo a Profile Optimizer change",
        "description": "Puts what was on the Google profile before that change back (the change ids are in `GET /v1/google-business/optimizer`, runs[].changes).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "change_id",
            "in": "path",
            "required": true,
            "description": "Change id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "change": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "run_id": "uuid",
                      "profile_id": "uuid",
                      "kind": "categories",
                      "summary": "Added HVAC contractor",
                      "applied_at": "2026-10-28T16:00:00Z",
                      "undone_at": "2026-10-29T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/map-rankings/keywords": {
      "post": {
        "operationId": "create_rank_keyword",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Track a Map Rankings keyword",
        "description": "Tracks where the business ranks on Google Maps for a search, across a grid of points centred on the business (or `center_lat` / `center_lng`).\n\n- On a schedule (weekly by default) its first scan runs within minutes and then on the schedule; each scan costs 0.25 (5x5), 0.5 (7x7), 1 (9x9) or 2 (13x13) credits from the account, the first 3 scans of a business are free.\n- Up to 10 keywords per business.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its profiles (default its first)."
                  },
                  "keyword": {
                    "type": "string",
                    "description": "What people search, e.g. \"furnace repair\" (up to 80 characters)."
                  },
                  "grid_size": {
                    "type": "number",
                    "description": "Points per side: 5, 7 (default), 9 or 13."
                  },
                  "spacing_m": {
                    "type": "number",
                    "description": "Meters between points: 402, 805, 1609 (default), 2414, 3219, 4828 or 8047."
                  },
                  "center_lat": {
                    "type": "number",
                    "description": "With center_lng: the grid's centre (default the business)."
                  },
                  "center_lng": {
                    "type": "number",
                    "description": "With center_lat."
                  },
                  "schedule": {
                    "type": "string",
                    "description": "Default weekly.",
                    "enum": [
                      "off",
                      "weekly",
                      "monthly"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "keyword"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "keyword": "furnace repair",
                "grid_size": 7,
                "schedule": "weekly"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "keyword": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "keyword": "furnace repair",
                      "grid_size": 7,
                      "spacing_m": 1609,
                      "center_lat": 30.33,
                      "center_lng": -81.66,
                      "schedule": "weekly",
                      "next_run_at": "2026-10-29T15:00:00Z",
                      "last_scan_at": null,
                      "paused_reason": null,
                      "created_at": "2026-10-29T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/map-rankings/keywords/{keyword_id}": {
      "patch": {
        "operationId": "update_rank_keyword",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change a tracked keyword",
        "description": "Changes a tracked search: how often it's scanned (schedule weekly, monthly or off), the search itself or its grid.\n\n- Send only what changes; the rest stays as saved.\n- A search never scanned that goes onto a schedule is scanned within minutes (credits, as a scan).\n- Its past scans stay, and `GET /v1/map-rankings?keyword_id=` reads its ranking over time.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyword_id",
            "in": "path",
            "required": true,
            "description": "Keyword id (GET /v1/map-rankings).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "schedule": {
                    "type": "string",
                    "description": "weekly, monthly or off.",
                    "enum": [
                      "off",
                      "weekly",
                      "monthly"
                    ]
                  },
                  "keyword": {
                    "type": "string",
                    "description": "What people search (up to 80 characters)."
                  },
                  "grid_size": {
                    "type": "number",
                    "description": "Points per side: 5, 7, 9 or 13."
                  },
                  "spacing_m": {
                    "type": "number",
                    "description": "Meters between points: 402, 805, 1609, 2414, 3219, 4828 or 8047."
                  },
                  "center_lat": {
                    "type": "number",
                    "description": "With center_lng: a new centre for the grid."
                  },
                  "center_lng": {
                    "type": "number",
                    "description": "With center_lat."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "schedule": "monthly"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "keyword": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "keyword": "furnace repair",
                      "grid_size": 7,
                      "spacing_m": 1609,
                      "center_lat": 30.33,
                      "center_lng": -81.66,
                      "schedule": "monthly",
                      "next_run_at": "2026-12-01T15:00:00Z",
                      "last_scan_at": "2026-11-01T15:02:00Z",
                      "paused_reason": null,
                      "created_at": "2026-10-28T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_rank_keyword",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Stop tracking a keyword",
        "description": "No more scans for it; its past scans stay readable.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyword_id",
            "in": "path",
            "required": true,
            "description": "Keyword id (GET /v1/map-rankings).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/map-rankings/keywords/{keyword_id}/scan": {
      "post": {
        "operationId": "start_rank_scan",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Scan a keyword now",
        "description": "Starts a scan of the keyword's grid (202): 0.25 to 2 credits by grid size, from the account (free for the first 3 scans of a business); points Google never answers are refunded.\n\n- One scan of a keyword at a time: while one runs, that one is returned.\n- It takes a few minutes; read it with `GET /v1/map-rankings/scans/{scan_id}`.\n- 402 when there aren't enough credits.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyword_id",
            "in": "path",
            "required": true,
            "description": "Keyword id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Accepted",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "scan": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "keyword_id": "uuid",
                      "keyword": "furnace repair",
                      "grid_size": 7,
                      "spacing_m": 1609,
                      "center_lat": 30.33,
                      "center_lng": -81.66,
                      "status": "running",
                      "trigger": "manual",
                      "credits": 0.5,
                      "summary": null,
                      "error": null,
                      "created_at": "2026-10-29T15:00:00Z",
                      "finished_at": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/listings/scan": {
      "post": {
        "operationId": "scan_listings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Check the business on the directories",
        "description": "The free check of every directory (202): starts Business Listings for the business, or looks again for the current run (at most every 6 hours).\n\n- business sets the details every directory gets (default: from its Google profile); they can change until something has been sent.\n- Read the results with `GET /v1/listings`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its profiles (default its first)."
                  },
                  "business": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "name, street, unit, city, state, zip, country, phone, website, email, category, categories, description, tagline, hours, services, first_name, last_name, year_founded, logo_url, service_area_only."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "campaign": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "status": "scanning",
                      "business": {
                        "name": "Acme HVAC"
                      },
                      "inbox_email": null,
                      "live": null,
                      "scanned_at": null,
                      "started_at": null,
                      "finished_at": null,
                      "recheck_at": null,
                      "created_at": "2026-10-29T15:00:00Z",
                      "updated_at": "2026-10-29T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/listings/start": {
      "post": {
        "operationId": "start_listings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Start listing the business",
        "description": "Signs the business up, with its details, on every directory the check didn't find it on or found with wrong details, as the app's Start: those listings are public.\n\n- 8 credits a directory from the account, refunded for each that ends without a listing; `credits_charged` says how many.\n- Some directories then need the owner (a code, a robot check): `GET /v1/listings` shows them.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "campaign_id": {
                    "type": "string",
                    "description": "Default the current run (GET /v1/listings)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "started": true,
                    "credits_charged": 96,
                    "campaign": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "status": "running"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/support/tickets": {
      "get": {
        "operationId": "list_support_tickets",
        "tags": [
          "Support"
        ],
        "summary": "Support tickets",
        "description": "The sub-account's Support tickets, newest activity first: subject, category, status (open, answered, resolved), who is answering (the assistant or the team), unread state and rating.\n\n- The agency team sees every ticket; a client admin every ticket of the sub-account; anyone else their own.\n- 403 `feature_off` while Support is off for the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter.",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "answered",
                "resolved"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_support_ticket",
        "tags": [
          "Support"
        ],
        "summary": "Open a support ticket",
        "description": "What the sub-account's Support page does: the ticket goes to the account's support team, their AI assistant answers first (usually within a minute; read the ticket for the answer) and hands it to a person when it can't solve it.\n\n- Replies also arrive by email.\n- Files are added in the app.\n- 403 `feature_off` while Support is off for the sub-account.\n\nWho can call it: Any member of the sub-account; at most 5 new tickets an hour per person.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "message": {
                    "type": "string",
                    "description": "What is going on (2-20,000 characters)."
                  },
                  "subject": {
                    "type": "string",
                    "description": "Up to 160 characters. Default: the start of the message."
                  },
                  "topic": {
                    "type": "string",
                    "description": "Default question.",
                    "enum": [
                      "question",
                      "problem",
                      "billing",
                      "request",
                      "ads",
                      "other"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "message"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "subject": "Texts not sending",
                "message": "Since this morning our texts to new leads fail. We changed nothing.",
                "topic": "problem"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ticket": {
                      "id": "uuid",
                      "number": 1031,
                      "workspace_id": "uuid",
                      "subject": "Texts not sending",
                      "category": "problem",
                      "status": "open",
                      "handler": "assistant",
                      "created_at": "2026-10-29T15:02:11Z"
                    },
                    "assistant_answering": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/support/tickets/{ticket_id}": {
      "get": {
        "operationId": "get_support_ticket",
        "tags": [
          "Support"
        ],
        "summary": "One support ticket and its messages",
        "description": "Every message in order (the customer, the assistant, the team), with the files' names. Internal notes only for the agency team.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "Ticket id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_support_ticket",
        "tags": [
          "Support"
        ],
        "summary": "Status, priority, assignee, who answers (support team)",
        "description": "The Support desk's changes, applied in this order: `assigned_to` (a team member's user id who can open the sub-account, or null to unassign; the new assignee is emailed and pushed the ticket), priority, handler (staff: the team answers from now on; assistant: hand it back, and the assistant answers at once if the client is waiting), status (resolved, or open to reopen).\n\n- If one fails, the ones before it stay.\n- Returns the ticket.\n- The agency's owners and team only.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "Ticket id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "description": "resolved closes it; open reopens it.",
                    "enum": [
                      "open",
                      "resolved"
                    ]
                  },
                  "priority": {
                    "type": "string",
                    "description": "Set by hand, it stays even when the assistant suggests another.",
                    "enum": [
                      "urgent",
                      "high",
                      "normal",
                      "low"
                    ]
                  },
                  "assigned_to": {
                    "type": "string",
                    "description": "A team member's user id, or null to unassign."
                  },
                  "handler": {
                    "type": "string",
                    "description": "Who answers the client.",
                    "enum": [
                      "staff",
                      "assistant"
                    ]
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "assigned_to": "uuid",
                "priority": "high",
                "handler": "staff"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ticket": {
                      "id": "uuid",
                      "number": 1031,
                      "status": "open",
                      "handler": "staff",
                      "assigned_to": "uuid",
                      "priority": "high"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/support/tickets/{ticket_id}/messages": {
      "post": {
        "operationId": "add_support_message",
        "tags": [
          "Support"
        ],
        "summary": "Add to a ticket (as the client)",
        "description": "A new message on a ticket the key's person opened (a client admin: any of the sub-account's tickets), as on the Support page.\n\n- While the assistant handles the ticket it answers again; otherwise the team is told.\n- `answered_by` says which.\n- The support team answers with `POST /v1/support/tickets/{ticket_id}/reply` instead (403 here).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "Ticket id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "Up to 20,000 characters."
                  }
                },
                "required": [
                  "message"
                ],
                "additionalProperties": true
              },
              "example": {
                "message": "Still failing after the restart."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ticket_id": "uuid",
                    "added": true,
                    "answered_by": "assistant"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/support/tickets/{ticket_id}/reply": {
      "post": {
        "operationId": "reply_support_ticket",
        "tags": [
          "Support"
        ],
        "summary": "Answer the client (support team)",
        "description": "The support team's reply, as from the Support desk: it shows on the client's Support page, is emailed to them (emailed says whether it went) and pushed to their phone.\n\n- A reply still holding [check: ...] parts (from the assistant's suggested reply) is refused until they are filled in.\n- The agency's owners and team only; others get 403.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "Ticket id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The reply, up to 20,000 characters."
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": true
              },
              "example": {
                "body": "Thanks Pat, your texting number was paused by the carrier. We've fixed it; texts are going out again."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ticket_id": "uuid",
                    "message_id": "uuid",
                    "emailed": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/support/tickets/{ticket_id}/notes": {
      "post": {
        "operationId": "add_support_note",
        "tags": [
          "Support"
        ],
        "summary": "Add an internal note (support team)",
        "description": "A note on the ticket only the support team sees; the client is not told. The agency's owners and team only.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "Ticket id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The note, up to 20,000 characters."
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": true
              },
              "example": {
                "body": "Carrier flagged the number on 10-28. Asked them to lift it."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ticket_id": "uuid",
                    "message_id": "uuid",
                    "internal": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/activity": {
      "get": {
        "operationId": "list_activity",
        "tags": [
          "Dashboard"
        ],
        "summary": "The Activity log",
        "description": "Everything that happened in the sub-account, newest first, as Settings > Activity log shows it: every change (the fields that changed, before and after, secrets hidden) with who made it (a person, an API key, the AI or an automation), their IP and browser, who opened what (contacts, conversations, recordings, exports), and messages, calls, bookings, automation runs, notifications and errors.\n\n- Keyset paged by `next_cursor`.\n- summary=true adds the page's counts by type and by day and who did the most.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "1-365, default 30.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO start, instead of days.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO end, default now.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Comma-separated: change, access, lead, inbound, outbound, ai, call, booking, appointment, automation, notification, webhook, api, error, system.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actor",
            "in": "query",
            "required": false,
            "description": "A user id, or user, api, ai, automation, lead or system.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "Only what happened to this lead.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Words in the title or description, or a contact's name, phone or email.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "summary",
            "in": "query",
            "required": false,
            "description": "Also return counts by type and day and the most active people.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "tz",
            "in": "query",
            "required": false,
            "description": "IANA time zone for summary days, default UTC.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-200, default 50.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "window": {
                      "from": "2026-09-24T00:00:00Z",
                      "to": "2026-10-24T00:00:00Z",
                      "days": 30
                    },
                    "activity": [
                      {
                        "id": "al:uuid",
                        "occurred_at": "2026-10-24T15:02:11Z",
                        "source": "al",
                        "category": "change",
                        "title": null,
                        "description": "Changed the AI texting settings",
                        "status": "ok",
                        "lead_id": null,
                        "lead_name": null,
                        "lead_phone": null,
                        "actor_id": "uuid",
                        "actor_kind": "api",
                        "actor_label": "API key · Zapier",
                        "actor_name": "Pat Owner",
                        "actor_email": "pat@example.com",
                        "metadata": null,
                        "audit": {
                          "entity_table": "workspace_outreach_settings",
                          "action": "update",
                          "changed_fields": [
                            "ai_reply_enabled"
                          ],
                          "old_values": {
                            "ai_reply_enabled": false
                          },
                          "new_values": {
                            "ai_reply_enabled": true
                          },
                          "ip_address": "203.0.113.4",
                          "user_agent": "Zapier",
                          "source": "api"
                        }
                      }
                    ],
                    "has_more": true,
                    "next_cursor": "MjAyNi0xMC0yNFQxNTowMjoxMVp8YWw6dXVpZA"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/review-requests": {
      "get": {
        "operationId": "list_review_requests",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "Who was asked for a review, and what they did",
        "description": "Sent, opened, rated (1-5), clicked through to a review site, and any private feedback, most recently active first.\n\nRequired scope: `leads:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "funnel_id",
            "in": "query",
            "required": false,
            "description": "One review page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "One lead.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "rated",
            "in": "query",
            "required": false,
            "description": "Only rated (true) or not yet rated (false).",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO time, changed at or after.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/review-link": {
      "post": {
        "operationId": "create_review_link",
        "tags": [
          "Invoices & reviews"
        ],
        "summary": "A lead's personal review link",
        "description": "Makes (or returns) the lead's link on a review page, like Copy review link on the lead. Sends nothing; share it however you like.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "funnel_id": {
                    "type": "string",
                    "description": "Which review page. Default: the default page."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead_id": "uuid",
                    "code": "k3x9p2",
                    "url": "https://app.example-agency.com/r/k3x9p2"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/notes/{note_id}": {
      "patch": {
        "operationId": "update_note",
        "tags": [
          "CRM leads"
        ],
        "summary": "Edit a note you wrote",
        "description": "Note ids are the note events in `GET /v1/leads/{lead_id}/timeline`. People can edit only their own notes, as in the app.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "note_id",
            "in": "path",
            "required": true,
            "description": "Note id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The note, max 4000."
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": true
              },
              "example": {
                "body": "Prefers a call after 5pm."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_note",
        "tags": [
          "CRM leads"
        ],
        "summary": "Delete a note",
        "description": "Owners and admins.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "note_id",
            "in": "path",
            "required": true,
            "description": "Note id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/leads/{lead_id}/do-not-contact": {
      "post": {
        "operationId": "set_do_not_contact",
        "tags": [
          "CRM leads"
        ],
        "summary": "Mark a lead do-not-contact",
        "description": "Like Do not contact on the Leads page: no more emails, and texts to the lead's number are blocked. The app has no undo, so it takes an owner or admin.\n\nRequired scope: `leads:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "Lead id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "lead_id": "uuid",
                    "do_not_contact": true,
                    "emails_blocked": true,
                    "texts_blocked": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/keys/self": {
      "get": {
        "operationId": "key_self",
        "tags": [
          "Account"
        ],
        "summary": "Inspect the calling API key",
        "description": "What this key may do and how much of it is used: `access_level` (read / write / admin / custom) and `scopes`, the `workspace` it is locked to (if any), `rate_limit_per_min`, `credit_budget` (limit, used, remaining and reset date; null when the key has no budget) and `usage_30d` (requests, errors, `rate_limited`).\n\n- `type` is `account` (made in Settings → API) or `sub_account` (made in a sub-account's own Settings → API in the client CRM), and `endpoints` gives the API and MCP addresses for the host you called.\n- A sub-account key can call this.\n\nRequired scope: `keys:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "key": {
                      "id": "uuid",
                      "key_prefix": "zu-ab12",
                      "name": "Zapier",
                      "is_active": true,
                      "access_level": "write",
                      "scopes": [
                        "write"
                      ],
                      "workspace": {
                        "id": "uuid",
                        "name": "Acme Roofing"
                      },
                      "rate_limit_per_min": 120,
                      "credit_budget": {
                        "limit_per_month": 500,
                        "used_this_month": 88,
                        "remaining": 412,
                        "resets_at": "2026-10-01T00:00:00Z"
                      },
                      "usage_30d": {
                        "requests": 1830,
                        "errors": 12,
                        "rate_limited": 0
                      },
                      "last_used_at": "2026-09-30T15:00:00Z",
                      "created_at": "2026-09-01T00:00:00Z",
                      "type": "account"
                    },
                    "endpoints": {
                      "api": "https://api.localflywheel.com/v1",
                      "mcp": "https://api.localflywheel.com/mcp"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard": {
      "get": {
        "operationId": "get_click_guard",
        "tags": [
          "Click Guard"
        ],
        "summary": "Click fraud: the protection score, invalid clicks, what they cost, blocked addresses",
        "description": "From the Website Analytics line on the sub-account's website, which watches every visit from its Google and Meta ads (robots included).\n\n- protection is 0-100 with items (what's done, what's missing); totals and `period_before` hold clicks, valid, suspicious, invalid, accidental, ignored (the ad platforms' own checkers), converted, `invalid_cost` (invalid clicks x the account's own cost per click from Google Ads, else the owner's `manual_cpc`), `blocked_now` and `blocked_new`.\n- savings: wasted, perMonth (that rate for 30 days), realClicks and leads that money buys at the account's conversion rate.\n- `why_invalid` groups clicks by their main reason (repeat, robot, hidden = servers / VPNs / Tor, area, competitor, farm, accidental); `by_day`, breakdowns (campaign, keyword, country, region, city, device, network, platform, browser), `latest_invalid`, `google_ads` (campaigns, cost per click, Google's own invalid clicks it didn't charge for, last sync and coverage), meta, setup and settings.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "protection": {
                      "score": 92,
                      "label": "Fully protected",
                      "items": [
                        {
                          "key": "tag",
                          "label": "Watching your ad clicks",
                          "done": true
                        }
                      ]
                    },
                    "totals": {
                      "clicks": 462,
                      "valid": 398,
                      "suspicious": 8,
                      "invalid": 56,
                      "invalid_cost": 326.4,
                      "blocked_now": 43
                    },
                    "savings": {
                      "wasted": 326.4,
                      "perMonth": 326.4,
                      "realClicks": 63,
                      "leads": 5
                    },
                    "currency": "USD",
                    "why_invalid": [
                      {
                        "category": "hidden",
                        "clicks": 28,
                        "cost": 147
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/clicks": {
      "get": {
        "operationId": "list_click_guard_clicks",
        "tags": [
          "Click Guard"
        ],
        "summary": "Ad clicks, newest first, with each one's score and reasons",
        "description": "Every ad click that reached the website: verdict (valid, suspicious, invalid, ignored), score 0-100, reasons (code, points, detail), category, ip (erased after 90 days), network (home, mobile, datacenter, vpn, relay), isp, place, device, campaign and keyword (from Google Ads), landing page, seconds on the page, cost, blocked, converted. 50 a page.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "verdict",
            "in": "query",
            "required": false,
            "description": "invalid, suspicious, valid or ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Starts of an IP address, or words in the city, network, campaign or keyword.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100 (default 50).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "total": 56,
                    "rows": [
                      {
                        "id": "6f0c...",
                        "at": "2026-11-18T12:30:00Z",
                        "ip": "159.89.172.197",
                        "verdict": "invalid",
                        "score": 100,
                        "reasons": [
                          {
                            "code": "datacenter",
                            "points": 75
                          }
                        ],
                        "network": "datacenter",
                        "isp": "DigitalOcean, LLC",
                        "campaign": "Garage Door Repair - Search",
                        "cost": 6.8,
                        "blocked": true
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/clicks/{click_id}": {
      "get": {
        "operationId": "get_click_guard_click",
        "tags": [
          "Click Guard"
        ],
        "summary": "One ad click in full, with the address's other clicks",
        "description": "What the browser said (automated or not, time zone, screen), what the visitor did (time on the page, scroll, moves, taps, first action), every reason with its points, the address's block (status, `expires_at`, `in_google`), and up to 30 other clicks from the same address or device.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "click_id",
            "in": "path",
            "required": true,
            "description": "A click (GET /v1/click-guard/clicks).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/blocks": {
      "get": {
        "operationId": "list_click_guard_blocks",
        "tags": [
          "Click Guard"
        ],
        "summary": "Blocked addresses and the never-block list",
        "description": "active (kept out of the ads: why, clicks, cost, place, network, `in_google`, `expires_at`), allowed (never blocked) and the last 100 expired. A block lasts 30 days after the last bad click (90 for servers and VPNs, 7 for phone networks); a block made by hand lasts until it's unblocked.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "block_click_guard_ip",
        "tags": [
          "Click Guard"
        ],
        "summary": "Block an IP address or range from the ads",
        "description": "Adds an address (203.0.113.7) or a CIDR range (203.0.113.0/24) to the block list; with automatic blocking on and Google Ads connected it reaches the account's IP exclusions within minutes. 409 when it's on the never-block list.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ip": {
                    "type": "string",
                    "description": "An IPv4 / IPv6 address or a CIDR range."
                  }
                },
                "required": [
                  "workspace_id",
                  "ip"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/unblock": {
      "post": {
        "operationId": "unblock_click_guard_ip",
        "tags": [
          "Click Guard"
        ],
        "summary": "Unblock an address (and optionally never block it again)",
        "description": "Takes the address off the block list (and out of Google Ads with the next sync). never: true also puts it on the never-block list and scores its recent clicks again.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ip": {
                    "type": "string",
                    "description": "The address or range."
                  },
                  "never": {
                    "type": "boolean",
                    "description": "Never block it again."
                  }
                },
                "required": [
                  "workspace_id",
                  "ip"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/settings": {
      "patch": {
        "operationId": "update_click_guard_settings",
        "tags": [
          "Click Guard"
        ],
        "summary": "Automatic blocking, how strict, the click limit, servers, VPNs, countries, never-block list",
        "description": "A rule change scores the last 7 days' clicks again.\n\nAny of:\n- enabled\n- `auto_block` (block in Google Ads by itself)\n- sensitivity (relaxed, standard, strict)\n- `click_limit` (0-20; 0 = no limit) and `click_limit_days` (1-30)\n- `block_servers`\n- `block_vpn`\n- countries (ISO codes served; empty = the business's own)\n- `allow_ips` (never block)\n- `meta_leads` (check leads from the ads for fakes)\n- `manual_cpc` (your cost per click, used only without Google Ads)\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Turn Click Guard on or off for the sub-account."
                  },
                  "meta_leads": {
                    "type": "boolean",
                    "description": "Check leads from the ads for fakes and keep them out of what Meta and Google learn from. Default true."
                  },
                  "auto_block": {
                    "type": "boolean",
                    "description": "Block in Google Ads by itself."
                  },
                  "sensitivity": {
                    "type": "string",
                    "description": "relaxed, standard or strict."
                  },
                  "click_limit": {
                    "type": "number",
                    "description": "Clicks allowed before a block (0 = no limit)."
                  },
                  "click_limit_days": {
                    "type": "number",
                    "description": "In how many days."
                  },
                  "block_servers": {
                    "type": "boolean",
                    "description": "Block cloud servers."
                  },
                  "block_vpn": {
                    "type": "boolean",
                    "description": "Block VPNs."
                  },
                  "countries": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Countries served (ISO codes)."
                  },
                  "allow_ips": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Never block these."
                  },
                  "manual_cpc": {
                    "type": "number",
                    "description": "Your cost per click without Google Ads."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/sync": {
      "post": {
        "operationId": "sync_click_guard",
        "tags": [
          "Click Guard"
        ],
        "summary": "Bring Google Ads' IP exclusions in line now",
        "description": "Reads the Google Ads account (campaigns, cost per click, Google's invalid clicks) and adds or removes Click Guard's addresses: the account-wide list first (every campaign type, Performance Max included, 500 at most), then each Search, Display and Shopping campaign's own list.\n\n- The business's own exclusions are never touched.\n- Answers added, removed and coverage.\n- It also runs by itself every few minutes.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/ask": {
      "post": {
        "operationId": "ask_click_guard",
        "tags": [
          "Click Guard"
        ],
        "summary": "Ask about the ad clicks in plain words",
        "description": "Answered from the business's own clicks, blocks and costs (never made up), with buttons into the tool and next questions. Pass `chat_id` back to continue a conversation. 40 questions a day per person.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "question": {
                    "type": "string",
                    "description": "The question."
                  },
                  "chat_id": {
                    "type": "string",
                    "description": "Continue this conversation."
                  },
                  "days": {
                    "type": "number",
                    "description": "How many days back (default 30)."
                  }
                },
                "required": [
                  "workspace_id",
                  "question"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/install": {
      "get": {
        "operationId": "get_click_guard_install",
        "tags": [
          "Click Guard"
        ],
        "summary": "The line of code for the website",
        "description": "The same line as Website Analytics (a site that has it needs nothing more), whether it's on the site, and the setup steps. Turns Click Guard on for the sub-account.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/leads": {
      "get": {
        "operationId": "list_click_guard_leads",
        "tags": [
          "Click Guard"
        ],
        "summary": "Leads from the ads that looked fake",
        "description": "Every lead from the sub-account's ads is checked a few minutes after it comes in: a Meta Instant Form lead from what it says (made-up names, numbers and emails, test entries, numbers that don't exist), a form or booking from the ad click its visit came from.\n\n- verdict junk = fake (a fake Instant Form lead is reported to Meta as DisqualifiedLead through Lead quality feedback; a form from a fake ad click is never sent to Meta), doubt = only marked.\n- meta: told | held | `no_dataset` (Lead quality feedback off).\n- Nothing is hidden or deleted.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "verdict",
            "in": "query",
            "required": false,
            "description": "junk (only fake) or all (every checked lead). Default: fake and doubtful.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "leads": [
                      {
                        "lead_id": "3f1c…",
                        "name": "Test Test",
                        "source": "instant_form",
                        "verdict": "junk",
                        "score": 100,
                        "why": "A test or made-up entry · A made-up phone number · A made-up email address",
                        "meta": "told",
                        "cleared_at": null,
                        "at": "2026-11-18T23:58:02Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/leads/{lead_id}/not-junk": {
      "post": {
        "operationId": "clear_click_guard_lead",
        "tags": [
          "Click Guard"
        ],
        "summary": "Mark a lead real (Not junk)",
        "description": "Its verdict never comes back, a report to Meta that hasn't gone out yet is stopped (`meta_stopped`), and its timeline says so.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "path",
            "required": true,
            "description": "The lead's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/meta-cleanup": {
      "get": {
        "operationId": "get_click_guard_meta_cleanup",
        "tags": [
          "Click Guard"
        ],
        "summary": "Which Meta ad sets show on Audience Network",
        "description": "Read only: the sub-account's active Meta ad sets that show ads inside other apps and sites (Audience Network), where accidental taps and junk clicks pile up. Needs Meta connected in Ad Insights.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "ad_account_id": "act_123",
                    "active": 6,
                    "on_audience_network": 2,
                    "ad_sets": [
                      {
                        "id": "120…",
                        "name": "Garage door repair - Austin"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "run_click_guard_meta_cleanup",
        "tags": [
          "Click Guard"
        ],
        "summary": "Turn off Audience Network in the Meta ad sets (or undo it)",
        "description": "Takes Audience Network out of every active ad set that shows there, keeping everything else; the ads keep running on Facebook, Instagram and Messenger.\n\n- Each ad set's earlier placements are kept, so undo: true puts them back.\n- Meta may review a changed ad set again (usually under a day).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "undo": {
                    "type": "boolean",
                    "description": "true puts the earlier placements back."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/click-guard/google-cleanup": {
      "get": {
        "operationId": "get_click_guard_google_cleanup",
        "tags": [
          "Click Guard"
        ],
        "summary": "Which Google campaigns show where junk clicks pile up",
        "description": "Read only: the sub-account's Google Ads campaigns (on or paused) with search partners on, the Display Network on a Search campaign, or ads shown to people only interested in the area (not in it), with what the clean-up would change in each.\n\n- Performance Max is left alone.\n- Needs Google Ads connected.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "campaigns": 3,
                    "items": [
                      {
                        "id": "24463672007",
                        "name": "Garage Door Repair - Search",
                        "fixes": [
                          "Search partners off",
                          "Display Network off",
                          "Only people in your area"
                        ]
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "run_click_guard_google_cleanup",
        "tags": [
          "Click Guard"
        ],
        "summary": "Clean up the Google campaigns (or undo it)",
        "description": "Turns search partners and the Display Network off on Search campaigns and shows the ads only to people in the targeted places, through the account's Google Ads change history (one row per kind of change, each with its own undo). undo: true puts every campaign back as it was; Google Ads History's own Undo does the same.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "undo": {
                    "type": "boolean",
                    "description": "true puts the earlier settings back."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-tracking": {
      "get": {
        "operationId": "get_call_tracking",
        "tags": [
          "Call Tracking"
        ],
        "summary": "Calls from tracking numbers: where they came from, answered, good leads, revenue",
        "description": "Tracking numbers show which ad, campaign, keyword and page made the phone ring: each website visitor sees their own number from a pool (the Website Analytics line swaps it), and a Google profile, flyer or truck gets a number each. totals (calls, `prev_calls` for the period before, `first_time`, answered, missed, voicemail, qualified = good leads + booked, booked, `avg_seconds`, `missed_from_ads` = callers from ads nobody answered or called back, leads, `revenue_cents` from callers whose jobs were won), series (per day), `series_by_channel`, channels, sources, campaigns, keywords, pages (landing pages), numbers, hours (weekday x hour, calls and missed), recent (the newest calls), pool (website numbers: size, `in_use` now, visits and shared = visits that had to share a number) and insights.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "totals": {
                      "calls": 30,
                      "prev_calls": 22,
                      "first_time": 20,
                      "answered": 20,
                      "missed": 4,
                      "voicemail": 6,
                      "qualified": 11,
                      "booked": 6,
                      "avg_seconds": 159,
                      "missed_from_ads": 6,
                      "leads": 21,
                      "revenue_cents": 1455000
                    },
                    "sources": [
                      {
                        "source": "Google Ads",
                        "channel": "Paid search",
                        "calls": 12,
                        "answered": 8,
                        "qualified": 6,
                        "booked": 3,
                        "revenue_cents": 485000
                      }
                    ],
                    "pool": {
                      "size": 4,
                      "in_use": 1,
                      "visits": 240,
                      "shared": 3
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-tracking/calls": {
      "get": {
        "operationId": "list_tracked_calls",
        "tags": [
          "Call Tracking"
        ],
        "summary": "Tracked calls, newest first, with where each came from and the AI's read",
        "description": "Each call: id, at, from, name (the lead's or the one the caller said), status, duration, voicemail, recording (true when there is one), `tracking_number` and `number_name`, kind (pool = a website number, source = one place's number), matched (visit, shared, none, source), channel, source, campaign, keyword, landing, `first_time`, label (the person's) and `ai_label`, summary, score (0-100 chance of becoming a customer), topic, `value_cents`, won, `called_back`, `lead_id` and `session_id` (the website visit).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "answered, missed, voicemail or not_called_back.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "label",
            "in": "query",
            "required": false,
            "description": "qualified (good leads and booked), booked, quote, customer, not_a_fit, vendor, spam, voicemail or unknown.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "e.g. Paid search, Paid social, Organic search, Google Business Profile, Offline.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "e.g. Google Ads, or a source number's name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign",
            "in": "query",
            "required": false,
            "description": "One campaign.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "description": "One keyword.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "number_id",
            "in": "query",
            "required": false,
            "description": "One tracking number.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "first_time",
            "in": "query",
            "required": false,
            "description": "true: first-time callers only.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "A name, number, keyword or what they wanted.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 200 (default 50).",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-tracking/calls/{call_id}": {
      "get": {
        "operationId": "get_tracked_call",
        "tags": [
          "Call Tracking"
        ],
        "summary": "One tracked call in full: the visit, the recording, transcript and the AI's read",
        "description": "Everything in the list, plus `recording_url`, transcript (lines by caller c / business b, written by a speech-to-text model; the AI reads only that, never the audio), `next_step`, amount (a price said on the call), the lead, the website visit (source, campaign, device, place, time on the site) with its pages in order, and the caller's other calls.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "description": "A call (GET /v1/call-tracking/calls).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_tracked_call",
        "tags": [
          "Call Tracking"
        ],
        "summary": "Mark what kind of call it was, or what it was worth",
        "description": "label wins over the AI's (null goes back to it). A call marked spam is given back: its talk time, recording and AI credits are refunded, up to 50 calls a month per sub-account.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "description": "The call.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "label": {
                    "type": "string",
                    "description": "booked, qualified, quote, customer, not_a_fit, vendor, spam, voicemail, missed, unknown, or null."
                  },
                  "value_cents": {
                    "type": "number",
                    "description": "What the call was worth, in cents, or null."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "label": "booked",
                "value_cents": 45000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-tracking/numbers": {
      "get": {
        "operationId": "list_tracking_numbers",
        "tags": [
          "Call Tracking"
        ],
        "summary": "The tracking numbers, the settings, and how many website numbers the traffic needs",
        "description": "numbers (`phone_number`, kind pool | source, name, preset, carrier, `bought_at`, `paid_until`), settings, `pool_advice` (recommended, why, measured: sized from the site's real traffic), traffic (visits a day, the busy-time number of visitors at once, the share from ads) and prices (credits: `number_monthly`, `per_leg_minute`, `recording_per_minute`, `ai_per_minute`).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_tracking_numbers",
        "tags": [
          "Call Tracking"
        ],
        "summary": "Add website numbers or a number for one place (spends credits)",
        "description": "kind pool adds count (1-10) website numbers; kind source adds one number for one place (preset gbp, `google_lsa`, yelp, angi, nextdoor, `facebook_page`, flyer, `direct_mail`, vehicle, `yard_sign`, billboard, radio, tv, print, email, other; name).\n\n- Local numbers in `area_code` (else the sub-account's), bought on the carrier of the line calls ring like.\n- Voice only: they never text, so they need no texting registration.\n- 15 credits a number a month, the first month now; 402 when the credits aren't there.\n\nRequired scope: `workspaces:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "kind": {
                    "type": "string",
                    "description": "pool or source.",
                    "enum": [
                      "pool",
                      "source"
                    ]
                  },
                  "count": {
                    "type": "number",
                    "description": "pool: how many, 1-10."
                  },
                  "preset": {
                    "type": "string",
                    "description": "source: where it's used."
                  },
                  "name": {
                    "type": "string",
                    "description": "source: its name in reports."
                  },
                  "area_code": {
                    "type": "string",
                    "description": "e.g. 512."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "kind": "source",
                "preset": "gbp",
                "name": "Google Business Profile",
                "area_code": "512"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-tracking/numbers/{number_id}": {
      "delete": {
        "operationId": "remove_tracking_number",
        "tags": [
          "Call Tracking"
        ],
        "summary": "Give a tracking number back",
        "description": "Calls to it stop working. Its calls stay in the history.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "number_id",
            "in": "path",
            "required": true,
            "description": "A number (GET /v1/call-tracking/numbers).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-tracking/settings": {
      "patch": {
        "operationId": "update_call_tracking_settings",
        "tags": [
          "Call Tracking"
        ],
        "summary": "Where calls ring, recording, which numbers the website swaps, for whom",
        "description": "route line (rings like `line_number`: the apps, ring order, AI receptionist, voicemail and missed-call text, as a call to it would) or forward (to `forward_to`, with `caller_id` caller | tracking and whisper: the person answering hears the source first). record + greeting (played to every caller before the call when recorded), ai (read recorded calls), `swap_numbers` (numbers on the site to replace), who (all, ads, `not_direct`), `hold_minutes` (10-120: how long a visitor keeps their number after their last activity), `area_code`, `google_ads` (a caller from a Google ad gets that click on their lead, so booked and won jobs count in Google Ads) and enabled (false stops swapping; the numbers keep ringing).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "route": {
                    "type": "string",
                    "description": "line or forward."
                  },
                  "line_number": {
                    "type": "string",
                    "description": "E.164, one of the sub-account's own lines."
                  },
                  "forward_to": {
                    "type": "string",
                    "description": "E.164."
                  },
                  "caller_id": {
                    "type": "string",
                    "description": "caller or tracking."
                  },
                  "whisper": {
                    "type": "boolean",
                    "description": "Forwarded calls: say the source first."
                  },
                  "record": {
                    "type": "boolean",
                    "description": "Record calls."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "The recording notice."
                  },
                  "swap_numbers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Numbers on the website to replace."
                  },
                  "who": {
                    "type": "string",
                    "description": "all, ads or not_direct."
                  },
                  "hold_minutes": {
                    "type": "number",
                    "description": "10-120."
                  },
                  "area_code": {
                    "type": "string",
                    "description": "For new numbers."
                  },
                  "ai": {
                    "type": "boolean",
                    "description": "Read recorded calls with AI."
                  },
                  "google_ads": {
                    "type": "boolean",
                    "description": "Give callers' leads their Google click."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Swap numbers on the website."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "route": "forward",
                "forward_to": "+15125550100",
                "whisper": true,
                "record": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/call-tracking/setup": {
      "post": {
        "operationId": "setup_call_tracking",
        "tags": [
          "Call Tracking"
        ],
        "summary": "Turn Call Tracking on and buy the website numbers",
        "description": "The settings (as `PATCH /v1/call-tracking/settings`) plus `pool_size`: buys the website numbers that are missing (up to 10 at a time; see `pool_advice`) and turns swapping on. Spends 15 credits a number for its first month.\n\nRequired scope: `workspaces:write`.\n\nSpends credits.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "pool_size": {
                    "type": "number",
                    "description": "How many website numbers (4-30)."
                  },
                  "swap_numbers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The numbers on the website."
                  },
                  "route": {
                    "type": "string",
                    "description": "line or forward."
                  },
                  "line_number": {
                    "type": "string",
                    "description": "With route line."
                  },
                  "forward_to": {
                    "type": "string",
                    "description": "With route forward."
                  },
                  "caller_id": {
                    "type": "string",
                    "description": "caller or tracking."
                  },
                  "whisper": {
                    "type": "boolean",
                    "description": "Forwarded calls: say the source first."
                  },
                  "record": {
                    "type": "boolean",
                    "description": "Record calls."
                  },
                  "greeting": {
                    "type": "string",
                    "description": "The recording notice."
                  },
                  "who": {
                    "type": "string",
                    "description": "all, ads or not_direct."
                  },
                  "hold_minutes": {
                    "type": "number",
                    "description": "10-120."
                  },
                  "area_code": {
                    "type": "string",
                    "description": "For new numbers."
                  },
                  "ai": {
                    "type": "boolean",
                    "description": "Read recorded calls with AI."
                  },
                  "google_ads": {
                    "type": "boolean",
                    "description": "Give callers' leads their Google click."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "pool_size": 5,
                "swap_numbers": [
                  "+15125550100"
                ],
                "route": "line",
                "line_number": "+15125550100",
                "record": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "402": {
            "$ref": "#/components/responses/ConfirmationRequired"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics": {
      "get": {
        "operationId": "get_website_analytics",
        "tags": [
          "Website Analytics"
        ],
        "summary": "The website's numbers: visitors, sources and ads, pages, conversions, frustration",
        "description": "From the line of code on the sub-account's website (`GET /v1/website-analytics/install`).\n\n- people only: robots, Meta's ad checkers and the team's own browsers are left out.\n- totals and previous (the same length before) hold visitors, sessions (visits), pageviews, `avg_s` (real attention time per visit), `bounce_rate` (one page, under 10 seconds, nothing done), converted / `conv_rate` (form sent, phone or email tapped, a thank-you page reached, or the site's own zs('convert')), `from_ads`, rage, dead, errors, `quick_backs`, `forms_started` / `forms_sent`.\n- series is one row per day (per hour for 2 days or less); dims has source, channel, campaign, utm_*, ad, referrer, country, region, city, device, browser, os, screen, language, entry, exit and visitor (new or returning), each row with visitors, sessions, bounce, `avg_s` and conv (percent).\n- pages, conversions, frustration (elements with rage and dead clicks), errors, hours (weekday, hour, visits), points (map), live (people in the last 5 minutes).\n- Heatmaps and recordings are in the app.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "How many days back, 1-400 (default 30).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Only visits that opened this page path.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Only this source (as dims.source names it, e.g. Meta Ads).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "device",
            "in": "query",
            "required": false,
            "description": "Desktop, Mobile or Tablet.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "2-letter country code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign",
            "in": "query",
            "required": false,
            "description": "A utm_campaign.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ad",
            "in": "query",
            "required": false,
            "description": "An ad platform (Meta Ads, Google Ads...).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "entry",
            "in": "query",
            "required": false,
            "description": "A landing page path.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timezone",
            "in": "query",
            "required": false,
            "description": "IANA zone for the day-by-day line (default UTC).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "totals": {
                      "visitors": 1240,
                      "sessions": 1510,
                      "pageviews": 3920,
                      "avg_s": 74,
                      "bounce_rate": 31.5,
                      "converted": 96,
                      "conv_rate": 6.4,
                      "from_ads": 610,
                      "rage": 22,
                      "dead": 140
                    },
                    "previous": {
                      "visitors": 1010,
                      "sessions": 1230,
                      "conv_rate": 5.1
                    },
                    "pages": [
                      {
                        "path": "/",
                        "views": 1800,
                        "visitors": 1100,
                        "avg_s": 41,
                        "scroll": 58,
                        "exit_rate": 44,
                        "entries": 1200
                      }
                    ],
                    "dims": {
                      "source": [
                        {
                          "name": "Meta Ads",
                          "visitors": 520,
                          "sessions": 610,
                          "bounce": 44,
                          "avg_s": 32,
                          "conv": 4.8
                        }
                      ]
                    },
                    "conversions": [
                      {
                        "name": "Form sent",
                        "n": 71,
                        "sessions": 70
                      }
                    ],
                    "live": 3
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/install": {
      "get": {
        "operationId": "get_website_install",
        "tags": [
          "Website Analytics"
        ],
        "summary": "The line of code for the website, and whether visits arrive",
        "description": "snippet goes inside the <head> of every page (WordPress, Wix, Squarespace, Shopify, Webflow, GoHighLevel and Google Tag Manager steps in steps). It loads after the page and hides everything typed. installed turns true with the first visit.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "site_id",
            "in": "query",
            "required": false,
            "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "snippet": "<script async src=\"https://crm.agency.com/api/public/w/AbC123xyZ9.js\"></script>",
                    "installed": true,
                    "last_seen_at": "2026-11-11T15:20:00Z",
                    "recordings": true,
                    "steps": "Paste the snippet inside the <head> of every page..."
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/sites": {
      "get": {
        "operationId": "list_website_sites",
        "tags": [
          "Website Analytics"
        ],
        "summary": "The sub-account's sites: each website and landing page it tracks",
        "description": "A sub-account can track several websites and landing pages, each with its own code and its own numbers, heatmaps and recordings, kept apart.\n\n- sites lists them, the first one first: id (send it as `site_id` on any `/v1/website-analytics` route), name, kind (website or landing), url, first, installed (visits arrive), `last_seen_at`, `last_host`, `visitors_7d`, `on_it_now`, recordings, `smart_page_ids` (Smart Pages that send their visits to it with no code) and snippet (its own line of code).\n- Opening the tool makes the first site.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sites": [
                      {
                        "id": "uuid",
                        "name": "acmeroofing.com",
                        "kind": "website",
                        "url": null,
                        "first": true,
                        "installed": true,
                        "last_seen_at": "2026-11-19T15:20:00Z",
                        "last_host": "acmeroofing.com",
                        "visitors_7d": 412,
                        "on_it_now": 3,
                        "recordings": true,
                        "smart_page_ids": [],
                        "snippet": "<script async src=\"https://crm.agency.com/api/public/w/AbC123xyZ9.js\"></script>"
                      },
                      {
                        "id": "uuid",
                        "name": "Spring roof sale",
                        "kind": "landing",
                        "url": "https://acmeroofing.com/spring-sale",
                        "first": false,
                        "installed": true,
                        "last_seen_at": "2026-11-19T15:18:00Z",
                        "last_host": "acmeroofing.com",
                        "visitors_7d": 96,
                        "on_it_now": 1,
                        "recordings": true,
                        "smart_page_ids": [],
                        "snippet": "<script async src=\"https://crm.agency.com/api/public/w/Qr7TuV2mN4.js\"></script>"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_website_site",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Add a website or landing page with its own code and numbers",
        "description": "Makes another site for the sub-account (up to 25): its own line of code (snippet), and from the first visit its own visitors, heatmaps, recordings and Ask AI, apart from the other sites.\n\n- name is what the switcher shows (unique in the sub-account, up to 60 characters).\n- kind is website (default) or landing.\n- `smart_page_ids` makes it count those Smart Pages, with nothing to paste (a page belongs to one site: it leaves the site it was on).\n- Deleting a site is done in the app.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "What to call it, e.g. Spring roof sale."
                  },
                  "kind": {
                    "type": "string",
                    "description": "website (default) or landing."
                  },
                  "url": {
                    "type": "string",
                    "description": "Its address (optional)."
                  },
                  "smart_page_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Smart Pages that send their visits to this site."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Spring roof sale",
                "kind": "landing",
                "url": "https://acmeroofing.com/spring-sale"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "site": {
                      "id": "uuid",
                      "name": "Spring roof sale",
                      "kind": "landing",
                      "url": "https://acmeroofing.com/spring-sale",
                      "first": false,
                      "installed": false,
                      "last_seen_at": null,
                      "last_host": null,
                      "visitors_7d": 0,
                      "on_it_now": 0,
                      "recordings": true,
                      "smart_page_ids": [],
                      "snippet": "<script async src=\"https://crm.agency.com/api/public/w/Qr7TuV2mN4.js\"></script>"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/website-analytics/ask": {
      "post": {
        "operationId": "ask_website_analytics",
        "tags": [
          "Website Analytics"
        ],
        "summary": "Ask about the website in plain words",
        "description": "Answered from the website's own numbers for the last days (visitors, pages, sources and ads, forms, what people click, frustration), with the numbers behind it, up to three actions (open a page's heatmap, watch recordings with a filter, narrow the overview), up to three prompts ready to paste into a website builder's AI or send to a web designer (title, for, text) and followups (likely next questions).\n\n- Each answer belongs to a saved conversation (`chat_id`, title; the same chats as the app's Ask AI): send `chat_id` back and it remembers the earlier questions and answers.\n- Free; 100 questions a week per sub-account (429 when used up, left = what's left this week).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "site_id": {
                    "type": "string",
                    "description": "One site of the sub-account (GET /v1/website-analytics/sites). Leave out for every site together."
                  },
                  "question": {
                    "type": "string",
                    "description": "e.g. Which page works best, and why?"
                  },
                  "chat_id": {
                    "type": "string",
                    "description": "Continue an earlier conversation (an answer's chat_id). Leave out to start a new one."
                  },
                  "days": {
                    "type": "number",
                    "description": "How many days back, 1-400 (default 30)."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA zone (default UTC)."
                  }
                },
                "required": [
                  "workspace_id",
                  "question"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "question": "Where do people get stuck on my website?",
                "days": 30
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "chat_id": "uuid",
                    "title": "Where do people get stuck on my website?",
                    "answer": "Most people who start your quote form stop at **Phone number** (7 of 22)...",
                    "actions": [
                      {
                        "type": "heatmap",
                        "page": "/contact",
                        "device": "Mobile",
                        "label": "See the form page on phones"
                      }
                    ],
                    "prompts": [
                      {
                        "title": "Make the phone field optional",
                        "for": "AI website builder",
                        "text": "You are editing my website acme.com. On the page acme.com/contact ..."
                      }
                    ],
                    "followups": [
                      "Is it the same on computers?",
                      "Write a prompt for my web designer"
                    ],
                    "left": 99
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports": {
      "get": {
        "operationId": "list_reports",
        "tags": [
          "Reports"
        ],
        "summary": "A sub-account's reports, with their email schedules and alerts",
        "description": "Every saved report: name, what it covers (sources), its dates, the share link when on, its scheduled emails (describe says when, `next_run_at` the next one) and alerts. 403 `feature_off` for a client when the agency hides Reports.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "reports": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Monthly marketing report",
                        "description": "Leads, where they came from, what the ads cost and the revenue they brought in.",
                        "sources": [
                          "leads",
                          "appointments",
                          "sales",
                          "meta",
                          "google_ads",
                          "ads"
                        ],
                        "doc": {
                          "v": 1,
                          "range": {
                            "preset": "last_month"
                          },
                          "compare": "previous",
                          "blocks": [
                            {
                              "id": "t2",
                              "type": "kpis",
                              "metrics": [
                                "leads.new",
                                "appointments.booked",
                                "sales.revenue",
                                "ads.cost_per_lead"
                              ]
                            }
                          ]
                        },
                        "template_key": "monthly_marketing",
                        "share_enabled": false,
                        "share_url": null,
                        "schedules": [
                          {
                            "id": "uuid",
                            "frequency": "monthly",
                            "day_of_month": 1,
                            "hour": 8,
                            "minute": 0,
                            "timezone": "America/New_York",
                            "recipients": [
                              "owner@acme.com"
                            ],
                            "format": {
                              "summary": true,
                              "pdf": true,
                              "link": true
                            },
                            "period": "schedule",
                            "enabled": true,
                            "next_run_at": "2026-12-01T13:00:00Z",
                            "describe": "On the 1st of every month at 8:00 AM"
                          }
                        ],
                        "alerts": [],
                        "last_sent_at": "2026-11-01T13:00:05Z",
                        "updated_at": "2026-11-09T18:20:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_report",
        "tags": [
          "Reports"
        ],
        "summary": "Make a report: ask for it in words, start from a ready-made one, or send its blocks",
        "description": "prompt: the AI builds it from plain words (\"a monthly report on leads and cost per lead, emailed to me on the 1st\") and saves it, plus its email schedule and alerts when the words ask for them (`with_schedule` false to skip); the answer has its reply.\n\n- template: a ready-made report (`GET /v1/reports/catalog`).\n- doc: your own blocks.\n- The report: {range: `{preset}`, compare: previous | year | none, blocks: [...]}.\n- Block types: kpis `{metrics}`, chart `{metrics, view: area | line | bar, group: auto | day | week | month}`, breakdown `{metric, by, view: bar | donut | table, limit}`, table `{table, limit}`, funnel, summary `{focus}`, heading `{text, sub}`, text `{text}`; any block takes title and width (full | half).\n- Metric keys, splits and tables: `GET /v1/reports/catalog`.\n- Unknown keys are dropped.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "prompt": {
                    "type": "string",
                    "description": "What to build, in plain words. The AI picks the numbers, charts and dates."
                  },
                  "template": {
                    "type": "string",
                    "description": "A ready-made report key: monthly_marketing, weekly_pipeline, ads_performance, calls_speed, google_presence, appointments, at_a_glance, daily_recap, sales_revenue, ai_assistant, local_seo, reviews, map_rankings, ai_visibility, website."
                  },
                  "doc": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The report's blocks (see the description)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters."
                  },
                  "description": {
                    "type": "string",
                    "description": "One line about what it answers."
                  },
                  "with_schedule": {
                    "type": "boolean",
                    "description": "prompt only: false = don't set up the emails it asked for."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "prompt": "How are my Facebook and Google ads doing? Cost per lead and cost per sale by campaign. Email it to me every Monday."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "reply": "I built \"Ads performance\" and set it to email you every Monday at 8:00 AM.",
                    "report": {
                      "id": "uuid",
                      "name": "Ads performance",
                      "sources": [
                        "leads",
                        "meta",
                        "google_ads",
                        "ads"
                      ]
                    },
                    "schedules": [
                      {
                        "id": "uuid",
                        "describe": "Every Monday at 8:00 AM",
                        "recipients": [
                          "owner@acme.com"
                        ]
                      }
                    ],
                    "alerts": []
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/catalog": {
      "get": {
        "operationId": "get_report_catalog",
        "tags": [
          "Reports"
        ],
        "summary": "What a report can show here: connected sources, team emails, ready-made reports",
        "description": "connected says which sources have data to show in this sub-account (Meta and Google Ads need Ad Insights, the Google profile needs Tools, rankings need a Map Rankings scan); team lists people to send to; templates are the ready-made reports (`POST /v1/reports` with template). The metric keys, splits and tables themselves are in the API docs and MCP tool reports (action catalog).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "connected": {
                      "leads": true,
                      "appointments": true,
                      "calls": true,
                      "meta": true,
                      "google_ads": false,
                      "gbp": true,
                      "rankings": false
                    },
                    "team": [
                      {
                        "user_id": "uuid",
                        "name": "Dana Lee",
                        "email": "dana@acme.com"
                      }
                    ],
                    "me": "owner@acme.com",
                    "timezone": "America/New_York",
                    "business": "Acme HVAC",
                    "templates": [
                      {
                        "key": "monthly_marketing",
                        "name": "Monthly marketing report",
                        "description": "Leads, where they came from, what the ads cost and the revenue they brought in.",
                        "audience": "For the owner",
                        "frequency": "monthly",
                        "sources": [
                          "leads",
                          "sales",
                          "meta",
                          "ads"
                        ]
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}": {
      "get": {
        "operationId": "get_report",
        "tags": [
          "Reports"
        ],
        "summary": "One report: its blocks, schedules, alerts and the emails it sent",
        "description": "sends are the last 25 emails (scheduled, sent now, tests, alerts) with when they went out and were opened; url is the frozen web copy that email links to.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "report": {
                      "id": "uuid",
                      "name": "Weekly sales pipeline"
                    },
                    "schedules": [],
                    "alerts": [],
                    "sends": [
                      {
                        "id": "uuid",
                        "kind": "scheduled",
                        "period_from": "2026-11-02",
                        "period_to": "2026-11-08",
                        "recipients": [
                          "owner@acme.com"
                        ],
                        "pdf": true,
                        "sent_at": "2026-11-09T13:00:04Z",
                        "opened_at": "2026-11-09T14:12:00Z",
                        "error": null,
                        "url": "https://crm.example.com/reports/9f1c2a"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_report",
        "tags": [
          "Reports"
        ],
        "summary": "Change a report by hand or by asking the AI",
        "description": "Send name, description or doc (the whole doc replaces it), or prompt to have the AI change it (\"add Google Ads spend\", \"show it by week\", \"email it monthly\"): it keeps what you didn't ask to change. Shows on the page at once.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "The change, in plain words."
                  },
                  "doc": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The whole report (see POST /v1/reports)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters."
                  },
                  "description": {
                    "type": "string",
                    "description": "One line."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "prompt": "Add Google Ads spend and cost per conversion under the Meta numbers"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "reply": "Added Google Ads spend and cost per conversion under the Meta numbers.",
                    "report": {
                      "id": "uuid",
                      "name": "Ads performance"
                    },
                    "schedules": [],
                    "alerts": []
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_report",
        "tags": [
          "Reports"
        ],
        "summary": "Delete a report, its schedules and alerts",
        "description": "Emails already sent keep their links.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}/data": {
      "get": {
        "operationId": "get_report_data",
        "tags": [
          "Reports"
        ],
        "summary": "A report's numbers for its dates, or others",
        "description": "Money is in the account's currency, percents are fractions (0.25 = 25%), speed in minutes.\n\nvalues:\n- metric -> [this period, compared period]\n- series: metric -> one value per day\n- breakdowns: metric|split -> rows\n- tables\n- summaries (the AI summary per summary block, summaries=false to skip)\n- sources says why a source has nothing (`not_connected`, error, `no_data`)\n\n- Leads leave out imported lists, spam, existing customers and chat-only people.\n- Meta, Google Ads and Google profile numbers are read live (Google's run about 3 days behind).\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "preset",
            "in": "query",
            "required": false,
            "description": "Other dates: last_7_days, last_30_days, this_month, last_month, last_quarter, this_year, custom ... (the report's own when left out).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "custom: first day, YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "custom: last day, YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "compare",
            "in": "query",
            "required": false,
            "description": "previous | year | none.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "summaries",
            "in": "query",
            "required": false,
            "description": "false = no AI summary.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "data": {
                      "tz": "America/New_York",
                      "currency": "USD",
                      "period": {
                        "from": "2026-10-01",
                        "to": "2026-10-31"
                      },
                      "compare": {
                        "from": "2026-09-01",
                        "to": "2026-09-30"
                      },
                      "values": {
                        "leads.new": [
                          197,
                          172
                        ],
                        "ads.cost_per_lead": [
                          35.37,
                          36.43
                        ]
                      },
                      "series": {
                        "leads.new": {
                          "cur": [
                            6,
                            8,
                            5
                          ],
                          "prev": [
                            5,
                            7,
                            6
                          ]
                        }
                      },
                      "breakdowns": {
                        "leads.new|source": [
                          {
                            "key": "meta_lead_ad",
                            "label": "Facebook lead form",
                            "cur": 86,
                            "prev": 71
                          }
                        ]
                      },
                      "tables": {},
                      "sources": {
                        "rankings": {
                          "state": "not_connected",
                          "message": "Run a Map Rankings scan in Tools to see where you show on Google Maps."
                        }
                      },
                      "summaries": {
                        "t1": "New leads went up 15% to 197, most from the Facebook lead form."
                      },
                      "generated_at": "2026-11-10T09:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}/send": {
      "post": {
        "operationId": "send_report",
        "tags": [
          "Reports"
        ],
        "summary": "Email a report now (or a test to yourself)",
        "description": "Freezes the numbers for the report's dates (or range) and emails them in the agency's brand: format `{summary: the numbers in the email, pdf: attached, link: to the web copy}`. test: true sends only to the key's person. At most 60 a day per sub-account.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "recipients": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Email addresses (up to 25)."
                  },
                  "test": {
                    "type": "boolean",
                    "description": "Send only to yourself."
                  },
                  "format": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{summary, pdf, link}, booleans."
                  },
                  "message": {
                    "type": "string",
                    "description": "A note at the top."
                  },
                  "subject": {
                    "type": "string",
                    "description": "{period} becomes the dates."
                  },
                  "range": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Other dates than the report's own: { preset, from, to } as GET .../data takes them."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "recipients": [
                  "owner@acme.com"
                ],
                "format": {
                  "summary": true,
                  "pdf": true,
                  "link": true
                },
                "message": "Here's October."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sent": true,
                    "to": [
                      "owner@acme.com"
                    ],
                    "url": "https://crm.example.com/reports/9f1c2a"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}/share": {
      "put": {
        "operationId": "share_report",
        "tags": [
          "Reports"
        ],
        "summary": "Turn a report's share link on or off, or make a new one",
        "description": "Anyone with the link sees the report with live numbers and can pick other dates, without signing in. `new_link`: true makes the old link stop working.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "On (default) or off."
                  },
                  "new_link": {
                    "type": "boolean",
                    "description": "Replace the link."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "enabled": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "report": {
                      "id": "uuid",
                      "share_enabled": true,
                      "share_url": "https://crm.example.com/reports/a902cee0b322"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}/schedules": {
      "post": {
        "operationId": "save_report_schedule",
        "tags": [
          "Reports"
        ],
        "summary": "Email a report every day, week, two weeks, month or quarter",
        "description": "frequency daily | weekly | biweekly | monthly | quarterly; `day_of_week` 0-6 (0 = Sunday), `day_of_month` 1-28, hour 0-23, minute 0 | 15 | 30 | 45, in timezone (the sub-account's when left out).\n\n- period schedule (default) covers the days before each email (the week before, the month before ...), report uses the report's own dates.\n- format `{summary, pdf, link}`.\n- Send id to change one.\n- Up to 10 per report.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "A schedule to change."
                  },
                  "frequency": {
                    "type": "string",
                    "description": "daily | weekly | biweekly | monthly | quarterly."
                  },
                  "day_of_week": {
                    "type": "number",
                    "description": "0-6, 0 = Sunday."
                  },
                  "day_of_month": {
                    "type": "number",
                    "description": "1-28."
                  },
                  "hour": {
                    "type": "number",
                    "description": "0-23."
                  },
                  "minute": {
                    "type": "number",
                    "description": "0, 15, 30 or 45."
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA zone."
                  },
                  "recipients": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Email addresses (up to 25)."
                  },
                  "format": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{summary, pdf, link}."
                  },
                  "period": {
                    "type": "string",
                    "description": "schedule | report."
                  },
                  "subject": {
                    "type": "string",
                    "description": "{period} becomes the dates."
                  },
                  "message": {
                    "type": "string",
                    "description": "A note at the top."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "false pauses it."
                  }
                },
                "required": [
                  "frequency",
                  "recipients"
                ],
                "additionalProperties": true
              },
              "example": {
                "frequency": "weekly",
                "day_of_week": 1,
                "hour": 8,
                "recipients": [
                  "owner@acme.com",
                  "sales@acme.com"
                ],
                "format": {
                  "summary": true,
                  "pdf": false,
                  "link": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "schedule": {
                      "id": "uuid",
                      "frequency": "weekly",
                      "day_of_week": 1,
                      "hour": 8,
                      "minute": 0,
                      "timezone": "America/New_York",
                      "recipients": [
                        "owner@acme.com",
                        "sales@acme.com"
                      ],
                      "enabled": true,
                      "next_run_at": "2026-11-16T13:00:00Z",
                      "describe": "Every Monday at 8:00 AM"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}/schedules/{schedule_id}": {
      "delete": {
        "operationId": "delete_report_schedule",
        "tags": [
          "Reports"
        ],
        "summary": "Stop a report's scheduled email",
        "description": "Required scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "schedule_id",
            "in": "path",
            "required": true,
            "description": "Schedule id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}/alerts": {
      "post": {
        "operationId": "save_report_alert",
        "tags": [
          "Reports"
        ],
        "summary": "Email someone when a number crosses a line",
        "description": "metric (a report metric key), op above | below, threshold (money in the account's currency, percents as fractions, speed in minutes), window day | week | month (yesterday, the last 7 or 30 days).\n\n- Checked every morning after 7 AM in the sub-account's time zone; emails once when it crosses, again only after it comes back.\n- Send id to change one.\n- Up to 20 per sub-account.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "An alert to change."
                  },
                  "metric": {
                    "type": "string",
                    "description": "e.g. ads.cost_per_lead, calls.missed, leads.new."
                  },
                  "op": {
                    "type": "string",
                    "description": "above | below."
                  },
                  "threshold": {
                    "type": "number",
                    "description": "The line."
                  },
                  "window": {
                    "type": "string",
                    "description": "day | week | month."
                  },
                  "recipients": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Email addresses."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "false pauses it."
                  }
                },
                "required": [
                  "metric",
                  "op",
                  "threshold",
                  "recipients"
                ],
                "additionalProperties": true
              },
              "example": {
                "metric": "ads.cost_per_lead",
                "op": "above",
                "threshold": 60,
                "window": "week",
                "recipients": [
                  "owner@acme.com"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "alert": {
                      "id": "uuid",
                      "metric": "ads.cost_per_lead",
                      "op": "above",
                      "threshold": 60,
                      "window": "week",
                      "recipients": [
                        "owner@acme.com"
                      ],
                      "enabled": true,
                      "tripped": false,
                      "describe": "Cost per lead goes above $60.00 over the last 7 days"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reports/{report_id}/alerts/{alert_id}": {
      "delete": {
        "operationId": "delete_report_alert",
        "tags": [
          "Reports"
        ],
        "summary": "Delete a report alert",
        "description": "Required scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report_id",
            "in": "path",
            "required": true,
            "description": "Report id (GET /v1/reports).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "alert_id",
            "in": "path",
            "required": true,
            "description": "Alert id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility": {
      "get": {
        "operationId": "get_ai_visibility",
        "tags": [
          "Ads & Google"
        ],
        "summary": "AI Visibility: how often AI assistants name the business",
        "description": "Does ChatGPT, Gemini, Google AI Mode / AI Overviews, Perplexity or Claude name this business when asked what its customers ask?\n\n- A check asks every question on every engine, several times where answers change.\n- The number is how often the business is named, always with the count (named of answers; rate is 0-1): answers don't repeat, so it is never a rank.\n- available is false until the feature is switched on, `set_up` false until `POST /v1/ai-visibility/setup`.\n\nlatest_check is the newest finished one:\n- per engine (`real_app` false = measured through its API, not its app)\n- per question (questions about the business by name don't count towards the rate)\n- `named_instead` (who else is named, by how many answers)\n- sources (the sites the answers read) and facts (is the phone, address and hours it gives right)\n\n- `wrong_details` lists what it gets wrong.\n- `last_four_weeks` and months add checks up, with `rate_low` and `rate_high` (a 90% range); trend says up or down only when the ranges don't overlap.\n- running is a check still going (about five minutes).\n- checks lists the newest 20 (`GET /v1/ai-visibility/checks/{check_id}` opens any one whole, to compare two dates); `steps_done` are plan steps someone ticked off.\n- `pricing.next_check_credits` is what the next check costs.\n- A sub-account can track several locations, one per Google profile: locations lists them with their latest count (`location_id` null = a Google profile not tracked yet), and everything else here is about one of them, its first unless `location_id` or `profile_id` says otherwise.\n- An add-on: 403 `addon_locked` without it.\n- 403 `feature_off` for a client when the agency hides Tools.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "required": false,
            "description": "Which tracked location (locations in GET /v1/ai-visibility). Leave out for the sub-account's first.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "Or which of the sub-account's Google profiles.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "available": true,
                    "set_up": true,
                    "settings": {
                      "business_name": "Acme Garage Doors",
                      "aliases": [],
                      "website": "acmedoors.com",
                      "phone": "8185550100",
                      "address": "1 Main St, Encino, CA",
                      "service": "garage door repair",
                      "town": "Encino",
                      "state": "CA",
                      "country": "US",
                      "claude": true,
                      "schedule": "weekly",
                      "next_check_at": "2026-11-15T12:00:00Z",
                      "last_check_at": "2026-11-08T12:00:00Z",
                      "paused_reason": null
                    },
                    "questions": [
                      {
                        "id": "uuid",
                        "text": "Who is the best garage door repair in Encino?",
                        "kind": "discovery"
                      }
                    ],
                    "running": null,
                    "latest_check": {
                      "id": "uuid",
                      "status": "done",
                      "trigger": "schedule",
                      "questions": 8,
                      "claude": true,
                      "credits": 12,
                      "credits_refunded": 0,
                      "named": 14,
                      "answers": 56,
                      "rate": 0.25,
                      "error": null,
                      "created_at": "2026-11-08T12:00:00Z",
                      "finished_at": "2026-11-08T12:06:00Z",
                      "by_engine": [
                        {
                          "engine": "chatgpt",
                          "label": "ChatGPT",
                          "real_app": true,
                          "named": 9,
                          "answers": 28,
                          "rate": 0.32
                        }
                      ],
                      "by_question": [
                        {
                          "id": "uuid",
                          "question": "Who is the best garage door repair in Encino?",
                          "kind": "discovery",
                          "counts_towards_rate": true,
                          "named": 4,
                          "answers": 15,
                          "rate": 0.27,
                          "by_engine": [
                            {
                              "engine": "chatgpt",
                              "named": 3,
                              "answers": 4
                            }
                          ]
                        }
                      ],
                      "named_instead": [
                        {
                          "name": "Precision Door",
                          "answers": 22,
                          "share": 0.39,
                          "website": "precisiondoor.net"
                        }
                      ],
                      "sources": [
                        {
                          "domain": "yelp.com",
                          "answers": 18,
                          "share": 0.32
                        }
                      ],
                      "facts": [
                        {
                          "engine": "chatgpt",
                          "label": "ChatGPT",
                          "answers": 4,
                          "named": 4,
                          "phone": {
                            "state": "wrong",
                            "said": "8185550000"
                          },
                          "address": {
                            "state": "right",
                            "said": "1 Main St"
                          },
                          "hours": {
                            "state": "none",
                            "days": []
                          },
                          "closed": false
                        }
                      ],
                      "answers_read": 120,
                      "answers_failed": 0,
                      "no_ai_overview": 3
                    },
                    "wrong_details": [
                      {
                        "engine": "chatgpt",
                        "label": "ChatGPT",
                        "what": "phone",
                        "said": "8185550000"
                      }
                    ],
                    "last_four_weeks": {
                      "named": 40,
                      "answers": 170,
                      "rate": 0.24,
                      "rate_low": 0.18,
                      "rate_high": 0.3,
                      "trend": "same",
                      "previous": {
                        "named": 30,
                        "answers": 160,
                        "rate": 0.19,
                        "rate_low": 0.14,
                        "rate_high": 0.25
                      }
                    },
                    "last_four_weeks_by_engine": [
                      {
                        "engine": "chatgpt",
                        "label": "ChatGPT",
                        "named": 26,
                        "answers": 84,
                        "rate": 0.31,
                        "rate_low": 0.23,
                        "rate_high": 0.4,
                        "trend": "same",
                        "previous": {
                          "named": 20,
                          "answers": 80,
                          "rate": 0.25,
                          "rate_low": 0.17,
                          "rate_high": 0.34
                        }
                      }
                    ],
                    "months": [
                      {
                        "month": "2026-11",
                        "checks": 2,
                        "named": 28,
                        "answers": 112,
                        "rate": 0.25,
                        "rate_low": 0.19,
                        "rate_high": 0.32,
                        "by_engine": [
                          {
                            "engine": "chatgpt",
                            "label": "ChatGPT",
                            "real_app": true,
                            "named": 18,
                            "answers": 56,
                            "rate": 0.32
                          }
                        ],
                        "businesses_named": 14,
                        "most_named": {
                          "name": "Precision Door",
                          "answers": 44
                        }
                      }
                    ],
                    "month_change": {
                      "trend": "same",
                      "points": 3
                    },
                    "checks": [
                      {
                        "id": "uuid",
                        "status": "done",
                        "trigger": "schedule",
                        "questions": 8,
                        "claude": true,
                        "credits": 12,
                        "credits_refunded": 0,
                        "named": 14,
                        "answers": 56,
                        "rate": 0.25,
                        "error": null,
                        "created_at": "2026-11-08T12:00:00Z",
                        "finished_at": "2026-11-08T12:06:00Z"
                      }
                    ],
                    "pricing": {
                      "credits_per_question": 0.75,
                      "claude_credits_per_question": 0.75,
                      "free_questions_on_first_check": 0,
                      "max_questions": 20,
                      "next_check_credits": 12
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/prefill": {
      "get": {
        "operationId": "get_ai_visibility_prefill",
        "tags": [
          "Ads & Google"
        ],
        "summary": "What the account already knows, for setting up AI Visibility",
        "description": "The business's name, website, phone, address, what it does, town and state, from its Google profile and sub-account, as the set-up screen fills them in; competitor is the one Map Rankings sees most.\n\n- `POST /v1/ai-visibility/setup` uses these for anything you leave out.\n- towns is the area around it, from its Google service area and neighborhoods.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "required": false,
            "description": "Which tracked location (locations in GET /v1/ai-visibility). Leave out for the sub-account's first.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "Or which of the sub-account's Google profiles.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "business_name": "Acme Garage Doors",
                    "website": "acmedoors.com",
                    "phone": "8185550100",
                    "address": "1 Main St, Encino, CA 91436, USA",
                    "service": "garage door repair",
                    "services": [
                      "Spring replacement"
                    ],
                    "town": "Encino",
                    "state": "CA",
                    "country": "US",
                    "competitor": "Precision Door",
                    "google_connected": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/ideas": {
      "post": {
        "operationId": "write_ai_visibility_questions",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Write questions customers would ask",
        "description": "The AI writes the questions to check, for this business, or plain templates when it can't. Free, and nothing is saved: pass them on to `POST /v1/ai-visibility/setup` or `PUT /v1/ai-visibility/questions`. Anything left out comes from what the account knows.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "business_name": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "service": {
                    "type": "string",
                    "description": "What it does, in a customer's words."
                  },
                  "services": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Other services (up to 8)."
                  },
                  "town": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "state": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "towns": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 5 towns around the location the questions also name."
                  },
                  "competitor": {
                    "type": "string",
                    "description": "A competitor, for the comparison question."
                  },
                  "location_id": {
                    "type": "string",
                    "description": "Which tracked location (locations in GET /v1/ai-visibility). Leave out for the sub-account's first."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "Or which of the sub-account's Google profiles."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "service": "garage door repair",
                "town": "Encino",
                "state": "CA"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "questions": [
                      {
                        "text": "Who is the best garage door repair in Encino?",
                        "kind": "discovery"
                      },
                      {
                        "text": "How much does a garage door spring cost in Encino?",
                        "kind": "cost"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/setup": {
      "post": {
        "operationId": "setup_ai_visibility",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Set up AI Visibility and start its first check",
        "description": "Saves the business's details and questions and starts the first check straight away.\n\n- Spends credits: 0.75 a question (1.50 with Claude, which is on by default), the first check's first 10 questions free; answers that never come back are refunded.\n- Anything left out comes from what the account knows (`GET /v1/ai-visibility/prefill`); 400 when it doesn't know `business_name`, service or town.\n- A question naming the business is added when none is sent.\n- Checks then run on schedule (weekly by default).\n- 409 `already_set_up` when that location already is: use `PUT /v1/ai-visibility/settings`, `PUT /v1/ai-visibility/questions` and `POST /v1/ai-visibility/check`.\n- To track another location send its `profile_id`, or `add_location` true with its details; only a sub-account's very first check has free questions.\n- 402 when there aren't enough credits.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ text, kind }] up to 20, at least one a customer would ask. kind: discovery, cost, branded (names the business) or comparison; left out, it's guessed from the words."
                  },
                  "business_name": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "aliases": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Other names it goes by (up to 6)."
                  },
                  "website": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "phone": {
                    "type": "string",
                    "description": "Default: the account's. The fact check compares with it."
                  },
                  "address": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "service": {
                    "type": "string",
                    "description": "What it does, in a customer's words."
                  },
                  "town": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "state": {
                    "type": "string",
                    "description": "Default: the account's."
                  },
                  "towns": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 5 towns around the location the questions also name."
                  },
                  "location_id": {
                    "type": "string",
                    "description": "Which tracked location (locations in GET /v1/ai-visibility). Leave out for the sub-account's first."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "Start tracking this Google profile."
                  },
                  "add_location": {
                    "type": "boolean",
                    "description": "A new location that isn't one of its Google profiles."
                  },
                  "claude": {
                    "type": "boolean",
                    "description": "Also ask Claude. Default true."
                  },
                  "schedule": {
                    "type": "string",
                    "description": "How often to check. Default weekly.",
                    "enum": [
                      "off",
                      "weekly",
                      "monthly"
                    ]
                  }
                },
                "required": [
                  "workspace_id",
                  "questions"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "questions": [
                  {
                    "text": "Who is the best garage door repair in Encino?",
                    "kind": "discovery"
                  },
                  {
                    "text": "How much does a garage door spring cost in Encino?",
                    "kind": "cost"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "check": {
                      "id": "uuid",
                      "status": "running",
                      "trigger": "first",
                      "questions": 3,
                      "claude": true,
                      "credits": 0,
                      "credits_refunded": 0,
                      "named": null,
                      "answers": null,
                      "rate": null,
                      "error": null,
                      "created_at": "2026-11-08T12:00:00Z",
                      "finished_at": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/settings": {
      "put": {
        "operationId": "update_ai_visibility_settings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change AI Visibility's settings",
        "description": "Send any of these; the rest stay as they are. A new schedule counts from now. 404 until it's set up.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "business_name": {
                    "type": "string",
                    "description": "Who counts as the business: this whole name, its phone or its website."
                  },
                  "aliases": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Other names it goes by (up to 6)."
                  },
                  "website": {
                    "type": "string",
                    "description": "Or null."
                  },
                  "phone": {
                    "type": "string",
                    "description": "Or null."
                  },
                  "address": {
                    "type": "string",
                    "description": "Or null."
                  },
                  "service": {
                    "type": "string",
                    "description": "What it does, or null."
                  },
                  "town": {
                    "type": "string",
                    "description": "Or null."
                  },
                  "state": {
                    "type": "string",
                    "description": "Or null."
                  },
                  "towns": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 5 towns around the location the questions also name."
                  },
                  "location_id": {
                    "type": "string",
                    "description": "Which tracked location (locations in GET /v1/ai-visibility). Leave out for the sub-account's first."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "Or which of the sub-account's Google profiles."
                  },
                  "claude": {
                    "type": "boolean",
                    "description": "Also ask Claude (costs more)."
                  },
                  "schedule": {
                    "type": "string",
                    "description": "How often to check.",
                    "enum": [
                      "off",
                      "weekly",
                      "monthly"
                    ]
                  },
                  "schedule_weekday": {
                    "type": "number",
                    "description": "Weekly checks: the day, 0 = Sunday ... 6 = Saturday. They run early that morning in the sub-account's time zone."
                  },
                  "schedule_monthday": {
                    "type": "number",
                    "description": "Monthly checks: the day of the month, 1-28."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "schedule": "monthly",
                "claude": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "settings": {
                      "business_name": "Acme Garage Doors",
                      "aliases": [],
                      "website": "acmedoors.com",
                      "phone": "8185550100",
                      "address": "1 Main St, Encino, CA",
                      "service": "garage door repair",
                      "town": "Encino",
                      "state": "CA",
                      "country": "US",
                      "claude": false,
                      "schedule": "monthly",
                      "next_check_at": "2026-12-08T12:00:00Z",
                      "last_check_at": "2026-11-08T12:00:00Z",
                      "paused_reason": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/questions": {
      "put": {
        "operationId": "set_ai_visibility_questions",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Replace the questions AI Visibility asks",
        "description": "Replaces the whole list: send every question to keep. A question that stays (same words) keeps its id and history. At least one a customer would ask, at most 20; a question naming the business is added when none is sent. 404 until it's set up.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ text, kind }]. kind: discovery, cost, branded (names the business) or comparison; left out, it's guessed from the words."
                  },
                  "location_id": {
                    "type": "string",
                    "description": "Which tracked location (locations in GET /v1/ai-visibility). Leave out for the sub-account's first."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "Or which of the sub-account's Google profiles."
                  }
                },
                "required": [
                  "workspace_id",
                  "questions"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "questions": [
                  {
                    "text": "Who is the best garage door repair in Encino?",
                    "kind": "discovery"
                  },
                  {
                    "text": "Is Acme Garage Doors any good?",
                    "kind": "branded"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "questions": [
                      {
                        "id": "uuid",
                        "text": "Who is the best garage door repair in Encino?",
                        "kind": "discovery"
                      },
                      {
                        "id": "uuid",
                        "text": "Is Acme Garage Doors any good?",
                        "kind": "branded"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/check": {
      "post": {
        "operationId": "start_ai_visibility_check",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Run an AI Visibility check now",
        "description": "Asks every question again, and takes about five minutes; read it with `GET /v1/ai-visibility`.\n\n- Spends credits: 0.75 a question, 1.50 with Claude (`pricing.next_check_credits` in `GET /v1/ai-visibility`); answers that never come back are refunded.\n- While one is running that one is returned and nothing is charged.\n- 402 when there aren't enough credits, 404 until it's set up.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "check": {
                      "id": "uuid",
                      "status": "running",
                      "trigger": "manual",
                      "questions": 8,
                      "claude": true,
                      "credits": 12,
                      "credits_refunded": 0,
                      "named": null,
                      "answers": null,
                      "rate": null,
                      "error": null,
                      "created_at": "2026-11-08T12:00:00Z",
                      "finished_at": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/answers": {
      "get": {
        "operationId": "get_ai_visibility_answers",
        "tags": [
          "Ads & Google"
        ],
        "summary": "The answers behind one question",
        "description": "Every answer to one question in one check, for reading: the words, who it named in the order it named them (you is this business) and the sites it read.\n\n- repeat is which time it was asked; `asked_from` says how (Google AI Mode: `computer_nearby`, `phone_nearby`, `computer_elsewhere` or `phone_elsewhere`).\n- `about_the_business` is what it said on a question naming the business.\n- The words of checks older than 180 days are gone; their numbers stay.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "check_id",
            "in": "query",
            "required": true,
            "description": "latest_check.id from GET /v1/ai-visibility.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "question",
            "in": "query",
            "required": true,
            "description": "The question exactly as by_question has it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "engine",
            "in": "query",
            "required": false,
            "description": "Only this engine.",
            "schema": {
              "type": "string",
              "enum": [
                "chatgpt",
                "gemini",
                "ai_mode",
                "aio",
                "perplexity",
                "claude"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "check_id": "uuid",
                    "question": "Who is the best garage door repair in Encino?",
                    "answers": [
                      {
                        "engine": "chatgpt",
                        "label": "ChatGPT",
                        "repeat": 1,
                        "asked_from": null,
                        "status": "done",
                        "no_answer": false,
                        "answer": "A few options in Encino are Precision Door and Acme Garage Doors.",
                        "named": true,
                        "businesses": [
                          {
                            "name": "Precision Door",
                            "you": false,
                            "phone": null,
                            "website": "precisiondoor.net"
                          },
                          {
                            "name": "Acme Garage Doors",
                            "you": true,
                            "phone": null,
                            "website": "acmedoors.com"
                          }
                        ],
                        "sources": [
                          {
                            "domain": "yelp.com",
                            "url": "https://www.yelp.com/search",
                            "title": "Top 10 Garage Door Services"
                          }
                        ],
                        "about_the_business": null
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/checks/{check_id}/advice": {
      "get": {
        "operationId": "get_ai_visibility_advice",
        "tags": [
          "Ads & Google"
        ],
        "summary": "What to do next, from one check",
        "description": "A plan written from what the check measured, once per check, free, the first time it's asked for.\n\n- state: writing (ask again in a few seconds), ready, or none (the check isn't finished).\n- tool names the sub-account tool for a step: listings, reviews, google-optimizer, google-posts, google-embeds, smart-pages or null; copy is exact text to paste (robots.txt lines); `done_at` when someone ticked it off.\n- `website_prompts` are prompts to paste into the AI that edits the website (its builder's AI, ChatGPT or Claude), built from this check and the Google profile, never by a model: key crawlers, readable, details (with the business details markup), questions, services, or review (the last: for ChatGPT or Claude to read the site and suggest more); `website_prompts_all` is every website fix as one prompt, or null with fewer than two.\n- website is the plan's look at the business's site, what an AI crawler that runs no scripts reads there: reachable (status 403 = its firewall turned the check away, so what is on it is unknown and the rest is null, never false), `ai_crawlers_blocked` (by robots.txt), `words_without_scripts`, `business_markup` (schema.org with an address or phone), `faq_markup`, `phone_on_page`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "check_id",
            "in": "path",
            "required": true,
            "description": "Check id (GET /v1/ai-visibility).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "state": "ready",
                    "headline": "AI names you in a quarter of its answers; fix your phone number first",
                    "steps": [
                      {
                        "title": "Correct your phone number on the directories",
                        "why": "ChatGPT gives out an old number.",
                        "how": "Update Yelp and Angi, the two sites it reads most.",
                        "tool": "listings",
                        "copy": null,
                        "done_at": null
                      }
                    ],
                    "website": {
                      "site": "acmegaragedoors.com",
                      "reachable": true,
                      "status": 200,
                      "ai_crawlers_blocked": [
                        "GPTBot"
                      ],
                      "words_without_scripts": 640,
                      "business_markup": false,
                      "faq_markup": false,
                      "phone_on_page": true,
                      "checked_at": "2026-11-08T12:09:00Z"
                    },
                    "website_prompts": [
                      {
                        "key": "questions",
                        "title": "Add answers to the questions customers ask AI",
                        "why": "Asked \"who can fix a garage door spring today in Encino?\", AI named you in 0 of 15 answers.",
                        "text": "I'm improving my business's website so AI assistants ... read it correctly ..."
                      }
                    ],
                    "website_prompts_all": null,
                    "written_at": "2026-11-08T12:10:00Z"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "mark_ai_visibility_step",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Tick a plan step off",
        "description": "Marks a step of a check's plan done (or not done again with done false). The app's chart marks the day, `GET /v1/ai-visibility` lists it under `steps_done`, and the next check's plan knows it was done. Answers the plan.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "check_id",
            "in": "path",
            "required": true,
            "description": "Check id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "step": {
                    "type": "number",
                    "description": "The step's place in the plan, 0 for the first."
                  },
                  "done": {
                    "type": "boolean",
                    "description": "false un-ticks it (default true)."
                  }
                },
                "required": [
                  "step"
                ],
                "additionalProperties": true
              },
              "example": {
                "step": 0
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "state": "ready",
                    "headline": "AI names you in a quarter of its answers; fix your phone number first",
                    "steps": [
                      {
                        "title": "Correct your phone number on the directories",
                        "why": "ChatGPT gives out an old number.",
                        "how": "Update Yelp and Angi, the two sites it reads most.",
                        "tool": "listings",
                        "copy": null,
                        "done_at": "2026-11-10T16:00:00Z"
                      }
                    ],
                    "website": null,
                    "website_prompts": [],
                    "website_prompts_all": null,
                    "written_at": "2026-11-08T12:10:00Z"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ai-visibility/checks/{check_id}": {
      "get": {
        "operationId": "get_ai_visibility_check",
        "tags": [
          "Ads & Google"
        ],
        "summary": "One check, whole",
        "description": "Any check kept (`GET /v1/ai-visibility` lists the newest 20 under checks), as `latest_check` shows the newest: per engine and question, who is named instead, the sources, the facts it got right or wrong. Two of them side by side compare two dates; a check that isn't finished comes back without the breakdown.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "check_id",
            "in": "path",
            "required": true,
            "description": "Check id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "check": {
                      "id": "uuid",
                      "status": "done",
                      "trigger": "schedule",
                      "questions": 8,
                      "claude": false,
                      "credits": 6,
                      "credits_refunded": 0,
                      "named": 14,
                      "answers": 56,
                      "rate": 0.25,
                      "error": null,
                      "created_at": "2026-10-12T15:00:00Z",
                      "finished_at": "2026-10-12T15:40:00Z",
                      "by_engine": [],
                      "by_question": [],
                      "named_instead": [],
                      "sources": [],
                      "facts": [],
                      "answers_read": 56,
                      "answers_failed": 0,
                      "no_ai_overview": 2
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/ad-insights/cards": {
      "get": {
        "operationId": "get_ad_insights_cards",
        "tags": [
          "Ads & Google"
        ],
        "summary": "The cards at the top of Ad Insights and the custom metrics",
        "description": "What the key's person sees at the top of the sub-account's Ad Insights.\n\n- cards are in showing order, then the ones hidden (kind: standard, `ready_made`, custom).\n- source: personal (their own), team (saved for everyone) or default (the eight usual ones).\n- metrics are the custom metrics: format is what was picked, `shows_as` what auto comes to, problem why one can't be worked out.\n- numbers are what a formula can use; a percent is a fraction, as in a spreadsheet.\n- 403 `feature_off` for a client when the agency hides Ad Insights.\n\nWho can call it: Any member of the sub-account.\n\nRequired scope: `meta:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "source": "personal",
                    "has_team_cards": false,
                    "can_save_for_everyone": true,
                    "cards": [
                      {
                        "id": "spend",
                        "label": "Spend",
                        "kind": "standard",
                        "showing": true
                      },
                      {
                        "id": "m:ab12cd34",
                        "label": "Profit per sale",
                        "kind": "custom",
                        "showing": true
                      },
                      {
                        "id": "revenue",
                        "label": "Revenue",
                        "kind": "ready_made",
                        "showing": false
                      }
                    ],
                    "metrics": [
                      {
                        "id": "ab12cd34",
                        "card_id": "m:ab12cd34",
                        "name": "Profit per sale",
                        "formula": "AOV - CPA",
                        "format": "auto",
                        "shows_as": "money",
                        "per_campaign": true,
                        "problem": null
                      }
                    ],
                    "numbers": [
                      {
                        "name": "AOV",
                        "label": "Average order value",
                        "format": "money",
                        "from": "crm",
                        "description": "Revenue ÷ sales"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_ad_insights_cards",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change the Ad Insights cards and custom metrics",
        "description": "Starts from what the key's person sees now and shows on the page as soon as it's saved.\n\n- cards = the card ids to show, in order, and every other card hides.\n- metrics = metrics to add or change (by id, else by name): name, formula over the numbers GET lists (AOV - CPA, Revenue * 40% - Spend; + - * / and brackets), format auto (default), money, number, percent or ratio, `per_campaign` to make it a column of Campaign Performance; a new one's card shows last, a rename carries into the formulas using it, and a formula that can't be read is a 400 that says why.\n- `delete_metrics` = metric ids; refused when a metric you're keeping uses it.\n- Saves the person's own cards unless `for_everyone`: true (owners and admins: their cards become everyone's, and personal cards made before give way).\n- `for_everyone` alone saves what they see now.\n- reset: true drops their own cards.\n- Answers as GET does.\n\nRequired scope: `meta:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "cards": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Card ids to show, in order. Leave out to keep them."
                  },
                  "metrics": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "[{ id, name, formula, format, per_campaign }] to add or change. The others stay."
                  },
                  "delete_metrics": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Metric ids to delete."
                  },
                  "for_everyone": {
                    "type": "boolean",
                    "description": "Make these everyone's cards in the sub-account."
                  },
                  "reset": {
                    "type": "boolean",
                    "description": "Drop this person's own cards (back to the team's, or the usual ones). Goes alone."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "metrics": [
                  {
                    "name": "Profit per sale",
                    "formula": "AOV - CPA",
                    "format": "money",
                    "per_campaign": true
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workspace_id": "uuid",
                    "source": "personal",
                    "has_team_cards": false,
                    "can_save_for_everyone": true,
                    "cards": [
                      {
                        "id": "spend",
                        "label": "Spend",
                        "kind": "standard",
                        "showing": true
                      },
                      {
                        "id": "m:ab12cd34",
                        "label": "Profit per sale",
                        "kind": "custom",
                        "showing": true
                      }
                    ],
                    "metrics": [
                      {
                        "id": "ab12cd34",
                        "card_id": "m:ab12cd34",
                        "name": "Profit per sale",
                        "formula": "AOV - CPA",
                        "format": "money",
                        "shows_as": "money",
                        "per_campaign": true,
                        "problem": null
                      }
                    ],
                    "numbers": [
                      {
                        "name": "AOV",
                        "label": "Average order value",
                        "format": "money",
                        "from": "crm",
                        "description": "Revenue ÷ sales"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/media": {
      "get": {
        "operationId": "list_media",
        "tags": [
          "Media"
        ],
        "summary": "Media files",
        "description": "A sub-account's Media page: its images and videos, newest first. Owners and agency admins see everything; the client's own people see only files shared with them (`visible_to_client`).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folder_id",
            "in": "query",
            "required": false,
            "description": "Only this folder, or none for files in no folder.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only this kind.",
            "schema": {
              "type": "string",
              "enum": [
                "image",
                "video"
              ]
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Words in the name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "media": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "folder_id": "uuid",
                        "name": "Roof before",
                        "kind": "image",
                        "url": "https://.../roof.jpg",
                        "thumbnail_url": null,
                        "mime": "image/jpeg",
                        "size": 482113,
                        "width": 1600,
                        "height": 1200,
                        "duration_seconds": null,
                        "visible_to_client": true,
                        "source": "upload",
                        "source_tool": "api",
                        "added_by": "uuid",
                        "created_at": "2026-11-10T12:00:00Z"
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_media",
        "tags": [
          "Media"
        ],
        "summary": "Add a file from a link",
        "description": "Copies a public https link into the sub-account's Media, stored like an upload: PNG, JPG, WebP or GIF up to 15 MB, MP4, MOV or WebM up to 50 MB (the file's own bytes decide its type).\n\n- Larger files go through the Media page.\n- Owners and admins; a client admin's file is always shared with the client's team, an agency's starts hidden.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "url": {
                    "type": "string",
                    "description": "A public https link to the image or video."
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 120 characters. Default: the link's file name."
                  },
                  "folder_id": {
                    "type": "string",
                    "description": "A folder of this sub-account. Default: no folder."
                  },
                  "visible_to_client": {
                    "type": "boolean",
                    "description": "Whether the client's team sees it."
                  }
                },
                "required": [
                  "workspace_id",
                  "url"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "url": "https://example.com/roof.jpg",
                "name": "Roof before",
                "visible_to_client": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "media": {
                      "id": "uuid",
                      "name": "Roof before",
                      "kind": "image",
                      "url": "https://.../roof.jpg",
                      "visible_to_client": true
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/media/folders": {
      "get": {
        "operationId": "list_media_folders",
        "tags": [
          "Media"
        ],
        "summary": "Media folders",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "folders": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Job photos",
                        "color": "#3b82f6",
                        "position": 0,
                        "created_at": "2026-11-10T12:00:00Z",
                        "updated_at": "2026-11-10T12:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_media_folder",
        "tags": [
          "Media"
        ],
        "summary": "Make a folder",
        "description": "Owners and admins. New folders go last unless position says otherwise.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 60 characters."
                  },
                  "color": {
                    "type": "string",
                    "description": "One of the page's colors; null or left out is the default grey.",
                    "enum": [
                      "#3b82f6",
                      "#10b981",
                      "#f59e0b",
                      "#f97316",
                      "#ef4444",
                      "#ec4899",
                      "#8b5cf6",
                      "#64748b"
                    ]
                  },
                  "position": {
                    "type": "number",
                    "description": "Its place in the list, 0 first."
                  }
                },
                "required": [
                  "workspace_id",
                  "name"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "name": "Job photos",
                "color": "#3b82f6"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "folder": {
                      "id": "uuid",
                      "name": "Job photos",
                      "color": "#3b82f6",
                      "position": 3
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/media/folders/{folder_id}": {
      "patch": {
        "operationId": "update_media_folder",
        "tags": [
          "Media"
        ],
        "summary": "Rename, recolor or reorder a folder",
        "description": "Required scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folder_id",
            "in": "path",
            "required": true,
            "description": "The folder.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 60 characters."
                  },
                  "color": {
                    "type": "string",
                    "description": "One of the page's colors, or null.",
                    "enum": [
                      "#3b82f6",
                      "#10b981",
                      "#f59e0b",
                      "#f97316",
                      "#ef4444",
                      "#ec4899",
                      "#8b5cf6",
                      "#64748b"
                    ]
                  },
                  "position": {
                    "type": "number",
                    "description": "Its place in the list, 0 first."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "name": "Before and after"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "folder": {
                      "id": "uuid",
                      "name": "Before and after"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_media_folder",
        "tags": [
          "Media"
        ],
        "summary": "Delete a folder",
        "description": "The folder only: its files stay in the library, in no folder.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "folder_id",
            "in": "path",
            "required": true,
            "description": "The folder.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "uuid",
                    "deleted": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reward-games": {
      "get": {
        "operationId": "list_reward_games",
        "tags": [
          "Reward games"
        ],
        "summary": "Reward games",
        "description": "Tools > Reward Games: short games (spin the wheel, scratch card, pick a gift, slot machine, pop a balloon, prize drop) a business sends past customers and old leads.\n\n- Every play wins one of its own rewards, shown as a coupon, and playing is free.\n- Each game has its setup, rewards with each one's chance and how many were won, `share_url` (the public link for social or a flyer) and numbers: `added_by_send`, sent, opened, played, redeemed, friends (came through a friend's link), `friend_rewards`, booked (a sale, booking or coupon used after playing) and `booked_cents`.\n- Test plays never count.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "games": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "status": "live",
                        "name": "Customer thank-you",
                        "style": "wheel",
                        "scene": "night",
                        "accent": "",
                        "slice_colors": [],
                        "font": "bricolage",
                        "photo": "",
                        "photo_show": "some",
                        "headline": "A thank-you spin, on us",
                        "subhead": "Every spin wins something for your next visit.",
                        "button": "",
                        "claim_how": "book",
                        "terms": "One reward per customer.",
                        "expires_days": 14,
                        "referral": {
                          "on": true,
                          "reward": "$50 off"
                        },
                        "form": {
                          "on": false,
                          "email": "off",
                          "questions": []
                        },
                        "rewards": [
                          {
                            "id": "r1",
                            "label": "$25 off",
                            "detail": "Your next service",
                            "weight": 40,
                            "stock": null,
                            "won": 12,
                            "chance_pct": 40
                          }
                        ],
                        "message": "Hi {first_name}, it's {business}. Every spin wins: {link}",
                        "email_subject": "Your reward is waiting",
                        "share_url": "https://crm.example.com/play/abc123",
                        "page": "/clients/uuid/tools?tool=reward-games&game=uuid",
                        "numbers": {
                          "queued": 0,
                          "sent": 120,
                          "opened": 64,
                          "played": 41,
                          "redeemed": 9,
                          "failed": 2,
                          "skipped": 3,
                          "friends": 4,
                          "friend_rewards": 1,
                          "friend_rewards_redeemed": 0,
                          "added_by_send": 125,
                          "via_links": 6,
                          "everyone": 132,
                          "booked": 11,
                          "booked_cents": 420000,
                          "currency": "USD"
                        },
                        "created_at": "2026-11-05T15:00:00Z",
                        "updated_at": "2026-11-06T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_reward_game",
        "tags": [
          "Reward games"
        ],
        "summary": "Make a reward game (a draft)",
        "description": "A new draft, from a ready-made template or blank; anything else you send goes on top.\n\n- Nothing is sent, and its links don't work until it is live.\n- A game can never be tied to a review: wording about reviews or ratings anywhere is refused (Google's policy and the FTC rule).\n- Rewards are 3 to 8, each with a label of up to 24 characters; a blank game can start with none but can't go live or be sent until it has them.\n- Up to 50 games per sub-account.\n- Answers with the game as GET shows it.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "template": {
                    "type": "string",
                    "description": "Start from a ready-made game. Left out: blank.",
                    "enum": [
                      "win-back",
                      "tune-up",
                      "lost-quotes",
                      "refer-a-friend"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "description": "The game's name, up to 60 characters (only your team sees it)."
                  },
                  "style": {
                    "type": "string",
                    "description": "The game.",
                    "enum": [
                      "wheel",
                      "scratch",
                      "gifts",
                      "slots",
                      "balloons",
                      "drop"
                    ]
                  },
                  "scene": {
                    "type": "string",
                    "description": "The look of the page.",
                    "enum": [
                      "night",
                      "day",
                      "warm"
                    ]
                  },
                  "accent": {
                    "type": "string",
                    "description": "#RRGGBB, or empty for the business's own colour."
                  },
                  "slice_colors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The wheel's slices: 2 to 4 #RRGGBB, or empty for shades of the accent."
                  },
                  "font": {
                    "type": "string",
                    "description": "Headline font.",
                    "enum": [
                      "bricolage",
                      "montserrat",
                      "poppins",
                      "nunito",
                      "fredoka",
                      "oswald",
                      "playfair",
                      "fraunces"
                    ]
                  },
                  "photo": {
                    "type": "string",
                    "description": "A picture already stored with us (a media library link), or empty."
                  },
                  "photo_show": {
                    "type": "string",
                    "description": "How much of the photo shows.",
                    "enum": [
                      "little",
                      "some",
                      "lots"
                    ]
                  },
                  "headline": {
                    "type": "string",
                    "description": "Up to 60 characters."
                  },
                  "subhead": {
                    "type": "string",
                    "description": "Up to 120 characters."
                  },
                  "button": {
                    "type": "string",
                    "description": "The wheel's button, up to 24 characters."
                  },
                  "language": {
                    "type": "string",
                    "description": "The language of every word on the game, its texts and its emails. Stock wording follows it; the business's own stays.",
                    "enum": [
                      "en",
                      "fr",
                      "es",
                      "de",
                      "nl",
                      "pt-BR",
                      "pt",
                      "zh"
                    ]
                  },
                  "words": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The business's own words over the language's, by key: for example { continue: \"Je tente ma chance\", showButton: \"Montrer en magasin\", bookNow: \"Prendre rendez-vous\" }. Keys include the game's, the coupon's, the form's, the friend step's and the texts'; an unknown key is refused and lists them all. {braces} are filled in. \"\" puts a word back. The texting agreement and the rules can't be changed."
                  },
                  "claim_how": {
                    "type": "string",
                    "description": "How a reward is claimed.",
                    "enum": [
                      "book",
                      "call",
                      "show"
                    ]
                  },
                  "terms": {
                    "type": "string",
                    "description": "The business's fine print, up to 300 characters."
                  },
                  "expires_days": {
                    "type": "number",
                    "description": "Days a won reward stays good, 1-90."
                  },
                  "referral": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ on, reward }: the fixed reward a customer earns when a friend uses theirs (never an extra spin)."
                  },
                  "form": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Questions before playing: { on, email: off | optional | required, questions: [{ label, type: text | choice | choices | yesno, options, required }] }, up to 6. Answers never change what anyone wins."
                  },
                  "rewards": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "3 to 8 of { id, label, detail, weight (1-100), stock (null = no limit) }. A reward named by its id, or by the same label, keeps its won count."
                  },
                  "message": {
                    "type": "string",
                    "description": "The text sent with the link, up to 640 characters: {first_name}, {business}, {link}, {referral_reward}."
                  },
                  "email_subject": {
                    "type": "string",
                    "description": "The email's subject, up to 120 characters."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "template": "win-back",
                "name": "Spring thank-you",
                "expires_days": 30
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "game": {
                      "id": "uuid",
                      "status": "draft",
                      "name": "Spring thank-you",
                      "style": "wheel",
                      "share_url": "https://crm.example.com/play/abc123"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reward-games/{game_id}": {
      "get": {
        "operationId": "get_reward_game",
        "tags": [
          "Reward games"
        ],
        "summary": "One reward game: setup and results",
        "description": "The same fields as the list, for one game.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "game_id",
            "in": "path",
            "required": true,
            "description": "Game id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "game": {
                      "id": "uuid",
                      "status": "live",
                      "name": "Customer thank-you",
                      "numbers": {
                        "sent": 120,
                        "opened": 64,
                        "played": 41,
                        "redeemed": 9,
                        "booked": 11
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_reward_game",
        "tags": [
          "Reward games"
        ],
        "summary": "Change a reward game",
        "description": "Send only what changes: the fields of `POST /v1/reward-games`, and status.\n\n- status draft | live | paused | ended is the game's switch: live makes its links work (409 until it has 3 rewards in stock), paused shows a back-soon page and holds its queue, ended closes it.\n- New plays get the changes.\n- Reward won counts and the public link are the server's and can't be changed.\n- Wording about reviews is refused.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "game_id",
            "in": "path",
            "required": true,
            "description": "Game id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "description": "The game's switch.",
                    "enum": [
                      "draft",
                      "live",
                      "paused",
                      "ended"
                    ]
                  },
                  "headline": {
                    "type": "string",
                    "description": "Or any other field of POST /v1/reward-games."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "status": "paused"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "game": {
                      "id": "uuid",
                      "status": "paused",
                      "name": "Customer thank-you"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_reward_game",
        "tags": [
          "Reward games"
        ],
        "summary": "Delete a reward game",
        "description": "Deletes the game and everyone's plays and coupons with it. Links stop working. To stop a game but keep its results, set status ended instead.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "game_id",
            "in": "path",
            "required": true,
            "description": "Game id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reward-games/{game_id}/audience": {
      "post": {
        "operationId": "reward_game_audience",
        "tags": [
          "Reward games"
        ],
        "summary": "How many people a send would reach",
        "description": "Free, and sends nothing. count = who would get it; skipped = people left out (no number or email, opted out, already have this game). `at_least`: the sub-account is too big to count exactly. `per_send`: how many one send queues at most.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "game_id",
            "in": "path",
            "required": true,
            "description": "Game id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "audience": {
                    "type": "string",
                    "description": "Who.",
                    "enum": [
                      "past_customers",
                      "lost_quotes",
                      "quiet_leads",
                      "everyone"
                    ]
                  },
                  "channel": {
                    "type": "string",
                    "description": "How it would go.",
                    "enum": [
                      "sms",
                      "email"
                    ]
                  },
                  "tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads with any of these tags (GET /v1/tags)."
                  }
                },
                "required": [
                  "audience",
                  "channel"
                ],
                "additionalProperties": true
              },
              "example": {
                "audience": "past_customers",
                "channel": "sms"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "count": 318,
                    "sample_first_names": [
                      "Jane",
                      "Omar",
                      "Priya"
                    ],
                    "skipped": {
                      "no_contact": 12,
                      "opted_out": 4,
                      "already": 0
                    },
                    "at_least": false,
                    "per_send": 2000
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reward-games/{game_id}/send": {
      "post": {
        "operationId": "send_reward_game",
        "tags": [
          "Reward games"
        ],
        "summary": "Send a reward game to an audience",
        "description": "Messages real people.\n\n- Puts each person (up to 2,000 a send) in the queue with their own time, at the pace you ask or the recommended one (texts: half the daily texting limit a day; emails: 100 an hour), inside the business's sending hours and never past its daily limit, so a list is never sent all at once.\n- Quiet hours, STOP and do-not-text apply.\n- Each person gets a personal link once per game.\n- A draft goes live.\n- 409 when the game is paused or ended, has too few rewards or mentions reviews.\n- `more_not_sent`: people past the 2,000; send again later to reach them.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "game_id",
            "in": "path",
            "required": true,
            "description": "Game id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "audience": {
                    "type": "string",
                    "description": "Who.",
                    "enum": [
                      "past_customers",
                      "lost_quotes",
                      "quiet_leads",
                      "everyone"
                    ]
                  },
                  "channel": {
                    "type": "string",
                    "description": "How it goes.",
                    "enum": [
                      "sms",
                      "email"
                    ]
                  },
                  "tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only leads with any of these tags (GET /v1/tags)."
                  },
                  "pace": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ n, per: hour | day }: at most 500 an hour or 5,000 a day. Left out: the recommended pace."
                  }
                },
                "required": [
                  "audience",
                  "channel"
                ],
                "additionalProperties": true
              },
              "example": {
                "audience": "past_customers",
                "channel": "sms",
                "pace": {
                  "n": 100,
                  "per": "day"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "queued": 318,
                    "more_not_sent": 0,
                    "pace": {
                      "n": 100,
                      "per": "day"
                    },
                    "first_at": "2026-11-08T15:00:00Z",
                    "last_at": "2026-11-11T22:30:00Z"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reward-games/{game_id}/try": {
      "post": {
        "operationId": "try_reward_game",
        "tags": [
          "Reward games"
        ],
        "summary": "A test link for the team",
        "description": "A link to play the game yourself, drafts included. Never texted, uses no stock, never counted in the numbers.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "game_id",
            "in": "path",
            "required": true,
            "description": "Game id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "url": "https://crm.example.com/play/Ab12Cd34Ef56"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reward-games/{game_id}/plays": {
      "get": {
        "operationId": "list_reward_game_plays",
        "tags": [
          "Reward games"
        ],
        "summary": "Who got a game, who played, rewards and codes",
        "description": "Newest first. status is queued, sent, opened, played, redeemed, failed or skipped; kind is play, or bonus for a referrer's fixed reward; `not_sent_reason` says why one didn't go; answers are the game's questions.\n\nq finds a coupon code or a first name, then POST `.../plays/{play_id}/redeem` marks it used.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "game_id",
            "in": "path",
            "required": true,
            "description": "Game id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "Default all. won = played and not used yet; waiting = queued, sent or opened; friends = came through a friend, and their rewards.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "won",
                "redeemed",
                "waiting",
                "friends"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "A coupon code or first name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "plays": [
                      {
                        "id": "uuid",
                        "game_id": "uuid",
                        "lead_id": "uuid",
                        "lead_name": "Jane Doe",
                        "first_name": "Jane",
                        "kind": "play",
                        "source": "text",
                        "channel": "sms",
                        "status": "played",
                        "referred_by": null,
                        "reward_label": "$25 off",
                        "reward_detail": "Your next service",
                        "code": "ACD34F",
                        "expires_at": "2026-11-20T15:00:00Z",
                        "not_sent_reason": null,
                        "queued_at": "2026-11-05T15:00:00Z",
                        "sent_at": "2026-11-05T15:01:00Z",
                        "opened_at": "2026-11-06T02:00:00Z",
                        "played_at": "2026-11-06T02:01:00Z",
                        "redeemed_at": null,
                        "reminded_at": null,
                        "created_at": "2026-11-05T15:00:00Z",
                        "answers": [],
                        "email_given": null
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/reward-games/plays/{play_id}/redeem": {
      "post": {
        "operationId": "redeem_reward_game_play",
        "tags": [
          "Reward games"
        ],
        "summary": "Mark a reward used",
        "description": "The customer used their coupon. Notes it on the lead; when this player came through a friend, the friend gets the game's fixed referral reward by text (`friend_reward`).\n\n- Past its date it is redeemed anyway and says expired: the business decides.\n- undo: true marks it not used; a referral reward already given stays.\n- 409 when they haven't played.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "play_id",
            "in": "path",
            "required": true,
            "description": "Play id (GET .../plays; q finds it by code).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "undo": {
                    "type": "boolean",
                    "description": "Mark it not used yet."
                  }
                },
                "additionalProperties": true
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "play": {
                      "id": "uuid",
                      "status": "redeemed",
                      "kind": "play",
                      "reward_label": "$25 off",
                      "code": "ACD34F",
                      "first_name": "Jane",
                      "expires_at": "2026-11-20T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards": {
      "get": {
        "operationId": "list_loyalty_programs",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Loyalty card programs",
        "description": "The sub-account's loyalty programs, newest first, with their settings, design, join link (the QR code on the counter) and 30-day numbers: cards, active, invited, `in_apple`, `in_google`, `joined_30d`, `visits_30d`, `earned_30d`, `rewards_ready`, `rewards_used_30d`, `spend_30d`, `returning_30d`.\n\n- problems lists what must be fixed before a draft can go live.\n- wallets says whether Apple Wallet and Google Wallet passes are on.\n- Free.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "programs": [
                      {
                        "id": "uuid",
                        "kind": "stamps",
                        "kind_title": "Stamp card",
                        "status": "live",
                        "settings": {
                          "name": "Coffee club",
                          "goal": 10,
                          "rewards": [
                            {
                              "id": "r1",
                              "at": 10,
                              "label": "Free coffee",
                              "detail": "Any size"
                            }
                          ]
                        },
                        "design": {
                          "theme": "espresso",
                          "bg": "#3b2a22"
                        },
                        "join_url": "https://usezu.com/card/abc123",
                        "problems": [],
                        "numbers": {
                          "cards": 212,
                          "in_apple": 120,
                          "in_google": 41,
                          "visits_30d": 380,
                          "rewards_used_30d": 31
                        }
                      }
                    ],
                    "wallets": {
                      "apple": true,
                      "google": true
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_loyalty_program",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Make a loyalty program",
        "description": "A new draft: starter (from the catalog: its rules and look, in the business's logo), or kind with optional settings and design (missing fields take the kind's defaults). Turn it on with PATCH status live. Words about reviews or ratings are refused.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "starter": {
                    "type": "string",
                    "description": "A starter key from GET /v1/loyalty-cards/catalog."
                  },
                  "kind": {
                    "type": "string",
                    "description": "stamps, points, cashback, tiers, membership, multipass, coupon, gift or event."
                  },
                  "settings": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Rules: language (en, fr, es, de, nl, pt-BR, pt, zh: what customers read; a starter's words come in it), name, headline, goal, rewards [{ at, label, detail }], earn { per: visit | spend, spendCents, points }, cashbackPercent, tiers, perks, validMonths, offer, event, welcome, referral, birthday, winback, auto { invoicePaid, jobWon, appointmentDone, stripePaid, issue }, message (must hold {link}), maxPerDay, rewardDays, terms."
                  },
                  "design": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Look: theme, bg, fg, label, stripBg, stampOn, stampOff (#rrggbb), icon { kind: glyph | clay | image, name, url }, shape, empty, logo, logoText, stripImage, barcode, font."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards/catalog": {
      "get": {
        "operationId": "loyalty_catalog",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Card types and starters",
        "description": "The kinds of card (stamps, points, cashback, tiers, membership, multipass, coupon, gift, event) with what each suits, and the starters (a ready card for a coffee shop, salon, car wash, auto repair, home services, pet groomer, gym, spa, bakery, pizza, shop, a one-time offer, gift cards) to pass as starter to `POST /v1/loyalty-cards`.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards/{program_id}": {
      "get": {
        "operationId": "get_loyalty_program",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "A loyalty program",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_loyalty_program",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Change a loyalty program",
        "description": "Only what's sent: settings and design are merged into the saved ones, status is draft, live, paused or ended (live refuses a program that isn't ready and says why). Every card already in a wallet updates by itself within a minute.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "settings": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "See POST /v1/loyalty-cards."
                  },
                  "design": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "See POST /v1/loyalty-cards."
                  },
                  "status": {
                    "type": "string",
                    "description": "draft, live, paused or ended."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_loyalty_program",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Delete a loyalty program",
        "description": "With customers on it, answers 409 `has_cards` unless ?confirm=true (their cards stop working). End it instead to keep their history.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "confirm",
            "in": "query",
            "required": false,
            "description": "true to delete it with its cards.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards/{program_id}/members": {
      "get": {
        "operationId": "list_loyalty_members",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Who has a card",
        "description": "The program's cards, newest first: first name, phone, email, member number, balance fields (stamps, points, `credit_cents`, `uses_left`, visits, `spend_cents`, tier, `expires_at`), `in_apple_wallet`, `in_google_wallet`, `card_url` and `last_visit_at`.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Name, email, phone or member number.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "invited, active, expired or closed.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-200, default 50.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "next_before from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "issue_loyalty_card",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Give someone a card",
        "description": "For a lead in the CRM (`lead_id`) or someone new (contact: firstName, phone, email; matched to a lead first).\n\n- channel sms or email sends them their card's link right away (texts cost the usual text price).\n- A person who already has the card gets theirs back (created false).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lead_id": {
                    "type": "string",
                    "description": "A lead in the sub-account."
                  },
                  "contact": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ firstName, phone?, email? }"
                  },
                  "channel": {
                    "type": "string",
                    "description": "sms or email: send it now."
                  },
                  "gift_cents": {
                    "type": "number",
                    "description": "A gift card's starting balance."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards/{program_id}/import": {
      "post": {
        "operationId": "import_loyalty_members",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Import members",
        "description": "People and balances from another loyalty app, up to 100 a call: `{ name, phone?, email?, stamps?, points?, balance_cents?, visits_left?, visits?, birthday? (MM-DD) }`. Saved as customers with a card that isn't sent; send them later with POST `.../send` audience unsent.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "rows": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1 to 100 people."
                  }
                },
                "required": [
                  "rows"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards/{program_id}/audience": {
      "post": {
        "operationId": "loyalty_audience",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Who a send reaches",
        "description": "How many people POST `.../send` would reach (free, sends nothing): audience `past_customers`, recent (90 days), everyone, tagged (`tag_ids`) or unsent (cards made but never sent), channel sms or email. People who already have the card, opted out or can't get that channel are left out.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "audience": {
                    "type": "string",
                    "description": "past_customers, recent, everyone, tagged or unsent."
                  },
                  "channel": {
                    "type": "string",
                    "description": "sms or email."
                  },
                  "tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "With audience tagged."
                  }
                },
                "required": [
                  "audience",
                  "channel"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards/{program_id}/send": {
      "post": {
        "operationId": "send_loyalty_cards",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Send cards",
        "description": "Each person in the audience gets their own card, already filled in, by text or email, spread over the business's sending hours at the recommended pace (or pace `{ n, per: hour | day }`), never past the daily texting limit.\n\n- Up to 2,000 a send.\n- Turns a draft program live when it's ready.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "audience": {
                    "type": "string",
                    "description": "See .../audience."
                  },
                  "channel": {
                    "type": "string",
                    "description": "sms or email."
                  },
                  "tag_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "With audience tagged."
                  },
                  "pace": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ n, per }."
                  }
                },
                "required": [
                  "audience",
                  "channel"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-cards/{program_id}/messages": {
      "get": {
        "operationId": "list_loyalty_messages",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Notes to card holders",
        "description": "Required scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "send_loyalty_message",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "A note on card holders' lock screens",
        "description": "body (up to 240 characters) shows on the lock screen of everyone whose card is in Apple Wallet or Google Wallet, and on browsers that turned notifications on on their card page (both free); channel `wallet_then_text` also texts the rest, if they agreed to texts.\n\n- audience all, active, quiet, ready (a reward waiting), close (one or two stamps away) or new.\n- One a day per program; `send_at` schedules it.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "program_id",
            "in": "path",
            "required": true,
            "description": "A loyalty program (from GET /v1/loyalty-cards).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The note."
                  },
                  "audience": {
                    "type": "string",
                    "description": "Default all."
                  },
                  "channel": {
                    "type": "string",
                    "description": "wallet (default) or wallet_then_text."
                  },
                  "send_at": {
                    "type": "string",
                    "description": "ISO time."
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members": {
      "get": {
        "operationId": "find_loyalty_members",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Find cards",
        "description": "Cards across every program by name, phone or the 8-digit member number on the card (q), or a lead's cards (`lead_id`).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Name, email, phone or member number.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lead_id",
            "in": "query",
            "required": false,
            "description": "A lead's cards.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "invited, active, expired or closed.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-200.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}": {
      "get": {
        "operationId": "get_loyalty_member",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "A customer's card",
        "description": "The card with its balance, what it shows (face: headline, fields, the nudge like \"2 more stamps to a free coffee\"), rewards ready to use, every reward, and its history (each entry's id is what undo takes).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/earn": {
      "post": {
        "operationId": "loyalty_earn",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Add a visit or purchase",
        "description": "Stamps (one per visit, or per amount spent), points, cashback credit, a VIP level's spend or a membership check-in, by the program's rules; count gives stamps or points by hand.\n\n- A milestone gives its reward and the card's phone shows it.\n- ref (your order or receipt id) never counts twice.\n- Refused past the program's daily limit per card.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "spend_cents": {
                    "type": "number",
                    "description": "What they spent."
                  },
                  "count": {
                    "type": "number",
                    "description": "Stamps or points by hand."
                  },
                  "note": {
                    "type": "string",
                    "description": "Kept on the history."
                  },
                  "ref": {
                    "type": "string",
                    "description": "Your id for this purchase."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/use": {
      "post": {
        "operationId": "loyalty_use",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Use points, credit or a visit",
        "description": "`reward_id` trades points for one of the program's rewards; cents spends cashback credit or a gift card's balance; uses takes visits from a visit pack, a coupon's use or an event check-in.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reward_id": {
                    "type": "string",
                    "description": "A points reward's id."
                  },
                  "cents": {
                    "type": "number",
                    "description": "Credit or balance to use."
                  },
                  "uses": {
                    "type": "number",
                    "description": "Visits or uses (default 1)."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/refill": {
      "post": {
        "operationId": "loyalty_refill",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Add visits or money, renew",
        "description": "uses adds visits to a visit pack (default the pack's size), cents adds to a gift card, and a membership is renewed by the program's months.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "uses": {
                    "type": "number",
                    "description": "Visits to add."
                  },
                  "cents": {
                    "type": "number",
                    "description": "Money to add."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/rewards": {
      "post": {
        "operationId": "loyalty_give_reward",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Give a reward",
        "description": "A reward of your own on the card (a thank-you, a make-good); the customer's phone shows it.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "What it is."
                  },
                  "detail": {
                    "type": "string",
                    "description": "More about it."
                  }
                },
                "required": [
                  "label"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/adjust": {
      "post": {
        "operationId": "loyalty_adjust",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Set a balance",
        "description": "field stamps, points, `credit_cents`, `uses_left`, visits or `spend_cents` set to value (a correction, or a card moved from another app); kept on the history with note.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string",
                    "description": "Which balance."
                  },
                  "value": {
                    "type": "number",
                    "description": "0 or more."
                  },
                  "note": {
                    "type": "string",
                    "description": "Why."
                  }
                },
                "required": [
                  "field",
                  "value"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/undo": {
      "post": {
        "operationId": "loyalty_undo",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Take back a change",
        "description": "A stamp, points, a purchase, a use or a refill from the last 24 hours (`event_id` from the card's history): its balances come back and the rewards it gave are voided (refused when one was already used).\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_id": {
                    "type": "number",
                    "description": "The history entry."
                  }
                },
                "required": [
                  "event_id"
                ],
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/close": {
      "post": {
        "operationId": "loyalty_close",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Close a card",
        "description": "It stops earning and its Wallet pass shows it's closed. Reopen it any time.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "description": "Why."
                  }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-members/{card_id}/reopen": {
      "post": {
        "operationId": "loyalty_reopen",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Open a card again",
        "description": "Required scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "card_id",
            "in": "path",
            "required": true,
            "description": "A customer's card (from .../members or GET /v1/loyalty-members).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/loyalty-rewards/{reward_id}/redeem": {
      "post": {
        "operationId": "redeem_loyalty_reward",
        "tags": [
          "Loyalty cards"
        ],
        "summary": "Use a reward",
        "description": "A reward waiting on a card (a stamp card's free item, a birthday or welcome gift) was used. Refused when it was used, taken back or ran out.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reward_id",
            "in": "path",
            "required": true,
            "description": "From the card's rewards_ready.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links": {
      "get": {
        "operationId": "list_short_links",
        "tags": [
          "Short links"
        ],
        "summary": "Short links",
        "description": "The sub-account's short links, newest first, with clicks and QR scans.\n\n- A link without a domain lives at <CRM domain>/l/<key>; one on the business's own domain at https://<domain>/<key> (`short_url` has it).\n- state: active, `scheduled_end` (it has an end date or click limit), expired, `used_up` or disabled.\n- Free: short links never cost credits.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Words in the name, address or back-half.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Only links with this tag.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Only links on this domain (empty = the CRM's own address).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "description": "Default exclude.",
            "schema": {
              "type": "string",
              "enum": [
                "exclude",
                "include",
                "only"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Default newest.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest",
                "name"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "links": [
                      {
                        "id": "uuid",
                        "short_url": "https://go.example.com/spring",
                        "domain": "go.example.com",
                        "key": "spring",
                        "url": "https://example.com/spring-special?utm_source=flyer&utm_medium=print",
                        "title": "Spring flyer",
                        "tags": [
                          "print"
                        ],
                        "notes": "",
                        "pinned": false,
                        "archived": false,
                        "state": "active",
                        "clicks": 214,
                        "qr_scans": 160,
                        "last_clicked_at": "2026-11-10T18:22:00Z",
                        "expires_at": null,
                        "expired_url": null,
                        "click_limit": null,
                        "password": false,
                        "ios_url": null,
                        "android_url": null,
                        "geo": {},
                        "variants": [],
                        "og": null,
                        "pixels": {},
                        "utm": {
                          "utm_source": "flyer",
                          "utm_medium": "print"
                        },
                        "qr_image": "https://go.example.com/spring/qr.svg",
                        "page": "/clients/uuid/tools?tool=short-links&link=uuid",
                        "created_at": "2026-11-01T15:00:00Z",
                        "updated_at": "2026-11-01T15:00:00Z"
                      }
                    ],
                    "has_more": false,
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_short_link",
        "tags": [
          "Short links"
        ],
        "summary": "Make a short link",
        "description": "url is where people land (https:// is added when left out). Leave key out for a random back-half; a taken key is 409.\n\n- The page's title becomes the link's name unless you send one.\n- Everything else is optional and can be changed later, including url: printed QR codes keep working.\n- `qr_image` in the answer is the QR code (SVG) in the link's design; add ?qr=1 to the short link yourself to count scans apart from clicks.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "url": {
                    "type": "string",
                    "description": "Where people land."
                  },
                  "key": {
                    "type": "string",
                    "description": "The back-half: letters, numbers, - and _, up to 50. slug works too."
                  },
                  "domain": {
                    "type": "string",
                    "description": "One of GET /v1/short-links/domains (verified). Left out: the sub-account's default."
                  },
                  "title": {
                    "type": "string",
                    "description": "A name only the team sees."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 20."
                  },
                  "utm": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ source, medium, campaign, term, content }: added to url."
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "When it stops (ISO date). Then people go to expired_url, else a page saying it ended."
                  },
                  "expired_url": {
                    "type": "string",
                    "description": "Where people go once it ends."
                  },
                  "click_limit": {
                    "type": "number",
                    "description": "Stops after this many clicks."
                  },
                  "password": {
                    "type": "string",
                    "description": "People type it before they go on. Kept only as a hash."
                  },
                  "ios_url": {
                    "type": "string",
                    "description": "Where iPhones and iPads go: a web address, or an app link (instagram://user?username=you) that opens the app, with url as the fallback."
                  },
                  "android_url": {
                    "type": "string",
                    "description": "Where Android phones go; an app link works the same way."
                  },
                  "geo": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ \"CA\": \"https://...\" }: a country's visitors go to its own page (up to 30)."
                  },
                  "variants": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "A/B split: [{ url, weight }] (1-3, weights in percent; the main url keeps the rest)."
                  },
                  "og": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The card texts and posts show: { title, description, image }."
                  },
                  "pixels": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ meta, google, tiktok, linkedin }: retargeting pixels fired on the way through."
                  },
                  "cloak": {
                    "type": "boolean",
                    "description": "Show the page under the short address, so the short link stays in the address bar (sites that refuse frames get an Open button)."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Only the team sees them."
                  }
                },
                "required": [
                  "workspace_id",
                  "url"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "url": "example.com/spring-special",
                "key": "spring",
                "tags": [
                  "print"
                ],
                "utm": {
                  "source": "flyer",
                  "medium": "print"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "link": {
                      "id": "uuid",
                      "short_url": "https://crm.example.com/l/spring",
                      "key": "spring",
                      "url": "https://example.com/spring-special?utm_source=flyer&utm_medium=print",
                      "title": "Spring Special | Example Plumbing",
                      "state": "active",
                      "clicks": 0,
                      "qr_scans": 0,
                      "qr_image": "https://crm.example.com/l/spring/qr.svg"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/bulk": {
      "post": {
        "operationId": "bulk_create_short_links",
        "tags": [
          "Short links"
        ],
        "summary": "Make up to 100 short links",
        "description": "links is a list of addresses or `{ url, key?, title?, tags?, ... }` (any field of `POST /v1/short-links`); defaults applies to every one (tags, utm, domain...). Each is made on its own: results says which worked, in order.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "links": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 100."
                  },
                  "defaults": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Fields for every link."
                  }
                },
                "required": [
                  "workspace_id",
                  "links"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "links": [
                  "https://example.com/a",
                  {
                    "url": "https://example.com/b",
                    "key": "b-flyer"
                  }
                ],
                "defaults": {
                  "tags": [
                    "mailer"
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "created": 2,
                    "failed": 0,
                    "results": [
                      {
                        "index": 0,
                        "ok": true,
                        "link": {
                          "id": "uuid",
                          "short_url": "https://crm.example.com/l/k3m9p2"
                        }
                      },
                      {
                        "index": 1,
                        "ok": true,
                        "link": {
                          "id": "uuid",
                          "short_url": "https://crm.example.com/l/b-flyer"
                        }
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/stats": {
      "get": {
        "operationId": "short_link_stats_all",
        "tags": [
          "Short links"
        ],
        "summary": "Every link's numbers",
        "description": "Clicks for all the sub-account's links (or one tag's): totals against the same length of time before (previous), a series by hour (up to 2 days) or day in the business's time zone, breakdown by country, region, city, continent, device, browser, os, referrer, trigger (link or qr), target (which page a rule sent them to), hour and weekday, and the top links.\n\n- people counts different visitors (a salted fingerprint of IP and browser, never shown) and returning those who came back; visitors counts different people each day.\n- breakdown also has postal (ZIP), model (phone), `os_version`, `browser_version`, isp (network), language, `referrer_url` (the page they came from) and query (the link's own ?parameters), and points are map positions (city level).\n- Bots and link previews are recorded apart (`totals.bots`) and never counted.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "range",
            "in": "query",
            "required": false,
            "description": "Default 30d.",
            "schema": {
              "type": "string",
              "enum": [
                "24h",
                "7d",
                "30d",
                "90d",
                "12mo"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Or a start (ISO date)...",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "...and an end (default now). Up to 3 years.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tz",
            "in": "query",
            "required": false,
            "description": "IANA time zone for the series (default the sub-account's).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Only links with this tag.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Filter: only clicks from this country (any breakdown key works the same way: region, city, postal, continent, device, browser, os, model, referrer, trigger, target, isp, language, query).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "stats": {
                      "from": "2026-10-12T15:00:00Z",
                      "to": "2026-11-11T15:00:00Z",
                      "tz": "America/Chicago",
                      "bucket": "day",
                      "totals": {
                        "clicks": 412,
                        "scans": 230,
                        "visitors": 371,
                        "links": 9
                      },
                      "previous": {
                        "clicks": 280,
                        "scans": 120
                      },
                      "series": [
                        {
                          "t": "2026-11-10T00:00",
                          "clicks": 22,
                          "scans": 14
                        }
                      ],
                      "breakdown": {
                        "country": [
                          {
                            "key": "US",
                            "clicks": 401
                          }
                        ],
                        "city": [
                          {
                            "key": "Austin",
                            "clicks": 120,
                            "country": "US"
                          }
                        ],
                        "device": [
                          {
                            "key": "Mobile",
                            "clicks": 330
                          }
                        ],
                        "referrer": [
                          {
                            "key": "(direct)",
                            "clicks": 300
                          },
                          {
                            "key": "facebook.com",
                            "clicks": 61
                          }
                        ],
                        "trigger": [
                          {
                            "key": "qr",
                            "clicks": 230
                          },
                          {
                            "key": "link",
                            "clicks": 182
                          }
                        ]
                      },
                      "links": [
                        {
                          "id": "uuid",
                          "key": "spring",
                          "domain": "go.example.com",
                          "title": "Spring flyer",
                          "url": "https://example.com/spring-special",
                          "clicks": 214,
                          "scans": 160
                        }
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/check": {
      "post": {
        "operationId": "check_short_links",
        "tags": [
          "Short links"
        ],
        "summary": "Check that links still work",
        "description": "Opens every link's destination (or the ids sent, up to 300) and keeps the answer on the link (health: ok, status, `checked_at`): a page that stopped working shows as broken in the app. Free.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only these links."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "checked": 12,
                    "broken": 1,
                    "results": [
                      {
                        "id": "uuid",
                        "ok": false,
                        "status": 404
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/{link_id}": {
      "get": {
        "operationId": "get_short_link",
        "tags": [
          "Short links"
        ],
        "summary": "One short link",
        "description": "The link as `GET /v1/short-links` shows it.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "link_id",
            "in": "path",
            "required": true,
            "description": "Link id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "link": {
                      "id": "uuid",
                      "short_url": "https://crm.example.com/l/spring",
                      "key": "spring",
                      "url": "https://example.com/spring-special",
                      "clicks": 214,
                      "qr_scans": 160,
                      "state": "active"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "update_short_link",
        "tags": [
          "Short links"
        ],
        "summary": "Change a short link",
        "description": "Send only what changes: any field of `POST /v1/short-links`, plus pinned and archived (an archived link still works).\n\n- Changing url sends everyone, printed QR codes included, to the new page.\n- Changing key or domain makes a new address: the old one stops working.\n- password \"\" removes the password; utm alone re-tags the current url; null clears `expires_at`, `expired_url`, `click_limit`, `ios_url`, `android_url` or og.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "link_id",
            "in": "path",
            "required": true,
            "description": "Link id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "archived": {
                    "type": "boolean",
                    "description": "Hide it from the list; it keeps working."
                  },
                  "pinned": {
                    "type": "boolean",
                    "description": "Keep it at the top."
                  },
                  "url": {
                    "type": "string",
                    "description": "Where people land."
                  },
                  "key": {
                    "type": "string",
                    "description": "The back-half: letters, numbers, - and _, up to 50. slug works too."
                  },
                  "domain": {
                    "type": "string",
                    "description": "One of GET /v1/short-links/domains (verified). Left out: the sub-account's default."
                  },
                  "title": {
                    "type": "string",
                    "description": "A name only the team sees."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 20."
                  },
                  "utm": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ source, medium, campaign, term, content }: added to url."
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "When it stops (ISO date). Then people go to expired_url, else a page saying it ended."
                  },
                  "expired_url": {
                    "type": "string",
                    "description": "Where people go once it ends."
                  },
                  "click_limit": {
                    "type": "number",
                    "description": "Stops after this many clicks."
                  },
                  "password": {
                    "type": "string",
                    "description": "People type it before they go on. Kept only as a hash."
                  },
                  "ios_url": {
                    "type": "string",
                    "description": "Where iPhones and iPads go: a web address, or an app link (instagram://user?username=you) that opens the app, with url as the fallback."
                  },
                  "android_url": {
                    "type": "string",
                    "description": "Where Android phones go; an app link works the same way."
                  },
                  "geo": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ \"CA\": \"https://...\" }: a country's visitors go to its own page (up to 30)."
                  },
                  "variants": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "A/B split: [{ url, weight }] (1-3, weights in percent; the main url keeps the rest)."
                  },
                  "og": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The card texts and posts show: { title, description, image }."
                  },
                  "pixels": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ meta, google, tiktok, linkedin }: retargeting pixels fired on the way through."
                  },
                  "cloak": {
                    "type": "boolean",
                    "description": "Show the page under the short address, so the short link stays in the address bar (sites that refuse frames get an Open button)."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Only the team sees them."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "url": "https://example.com/summer-special",
                "tags": [
                  "print",
                  "summer"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "link": {
                      "id": "uuid",
                      "short_url": "https://crm.example.com/l/spring",
                      "url": "https://example.com/summer-special"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_short_link",
        "tags": [
          "Short links"
        ],
        "summary": "Delete a short link",
        "description": "The link, its QR code and its numbers are gone for good; anyone who opens it sees \"link not found\". To keep it working but out of the list, PATCH archived: true instead.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "link_id",
            "in": "path",
            "required": true,
            "description": "Link id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/{link_id}/stats": {
      "get": {
        "operationId": "short_link_stats",
        "tags": [
          "Short links"
        ],
        "summary": "One link's numbers",
        "description": "The numbers of `GET /v1/short-links/stats` for one link (no top links).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "link_id",
            "in": "path",
            "required": true,
            "description": "Link id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "range",
            "in": "query",
            "required": false,
            "description": "Default 30d.",
            "schema": {
              "type": "string",
              "enum": [
                "24h",
                "7d",
                "30d",
                "90d",
                "12mo"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Or a start (ISO date).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "And an end.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tz",
            "in": "query",
            "required": false,
            "description": "IANA time zone.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "stats": {
                      "totals": {
                        "clicks": 214,
                        "scans": 160,
                        "visitors": 198,
                        "links": 1
                      },
                      "previous": {
                        "clicks": 90,
                        "scans": 40
                      },
                      "series": [],
                      "breakdown": {
                        "device": [
                          {
                            "key": "Mobile",
                            "clicks": 190
                          }
                        ]
                      },
                      "links": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/{link_id}/clicks": {
      "get": {
        "operationId": "list_short_link_clicks",
        "tags": [
          "Short links"
        ],
        "summary": "A link's latest clicks",
        "description": "Newest first: when, QR scan or click, which page it went to, country, region, city, ZIP, map position, time zone, device and phone model, browser and OS with versions, language, the site and page they came from, the link's own ?parameters, the IP address (kept 90 days), network (ISP, ASN) and whether they came back. Robots are left out.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "link_id",
            "in": "path",
            "required": true,
            "description": "Link id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "clicks": [
                      {
                        "id": 1,
                        "link_id": "uuid",
                        "at": "2026-11-10T18:22:00Z",
                        "trigger": "qr",
                        "target": "main",
                        "country": "US",
                        "region": "Texas",
                        "city": "Austin",
                        "device": "Mobile",
                        "browser": "Safari",
                        "os": "iOS",
                        "referrer": null
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/domains": {
      "get": {
        "operationId": "list_short_link_domains",
        "tags": [
          "Short links"
        ],
        "summary": "The business's own short domains",
        "description": "Domains like go.yourbusiness.com that short links can use. verified: it's live. `dns_record` is what to add at the domain's DNS provider. `root_url`: where the bare domain goes; `not_found_url`: where an unknown back-half goes.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "domains": [
                      {
                        "id": "uuid",
                        "hostname": "go.example.com",
                        "verified": true,
                        "verified_at": "2026-11-01T15:00:00Z",
                        "root_url": "https://example.com/",
                        "not_found_url": null,
                        "last_check_error": null,
                        "last_checked_at": "2026-11-01T15:00:00Z",
                        "ssl_status": "active",
                        "created_at": "2026-11-01T14:40:00Z"
                      }
                    ],
                    "dns_record": {
                      "type": "CNAME",
                      "points_to": "portal.usezu.com"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "add_short_link_domain",
        "tags": [
          "Short links"
        ],
        "summary": "Add a short domain",
        "description": "Adds the domain and checks it at once. Point a CNAME record for it to `portal.usezu.com` (a bare domain: an ALIAS or ANAME record); it is checked every few minutes until it's live, usually 5-30 minutes.\n\n- Use a subdomain (go., link.), never the address of the main website.\n- Up to 10.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "hostname": {
                    "type": "string",
                    "description": "Like go.yourbusiness.com."
                  },
                  "root_url": {
                    "type": "string",
                    "description": "Where the bare domain goes."
                  },
                  "not_found_url": {
                    "type": "string",
                    "description": "Where an unknown back-half goes."
                  }
                },
                "required": [
                  "workspace_id",
                  "hostname"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "hostname": "go.example.com",
                "root_url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "domain": {
                      "id": "uuid",
                      "hostname": "go.example.com",
                      "verified": false,
                      "last_check_error": "No record found for go.example.com yet."
                    },
                    "check": {
                      "verified": false,
                      "error": "No record found for go.example.com yet.",
                      "dns": {
                        "found": null,
                        "expected": "portal.usezu.com",
                        "a_records": []
                      }
                    },
                    "dns_record": {
                      "type": "CNAME",
                      "points_to": "portal.usezu.com"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/domains/{domain_id}/verify": {
      "post": {
        "operationId": "verify_short_link_domain",
        "tags": [
          "Short links"
        ],
        "summary": "Check a short domain now",
        "description": "Looks at its DNS record and opens it. error says what's still missing.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "description": "Domain id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "check": {
                      "verified": true,
                      "error": null,
                      "dns": {
                        "found": "portal.usezu.com",
                        "expected": "portal.usezu.com",
                        "a_records": []
                      }
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/short-links/domains/{domain_id}": {
      "delete": {
        "operationId": "delete_short_link_domain",
        "tags": [
          "Short links"
        ],
        "summary": "Remove a short domain",
        "description": "Its short links and their QR codes stop working and are deleted with it.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "description": "Domain id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/surveys": {
      "get": {
        "operationId": "list_surveys",
        "tags": [
          "Smart forms"
        ],
        "summary": "Surveys",
        "description": "The sub-account's surveys: Smart Forms that ask for feedback (a funnel with no booking and no screening).\n\n- A survey never makes a lead: an answer lands on the lead the personal link belongs to, or on one matched by the phone or email typed, else it stays on the survey.\n- Each has live, the message its link goes out in, rules (when it sends itself) and its questions.\n- Add or change questions with `PATCH /v1/smart-forms/{form_id}` (questions).\n\nRequired scope: `smart_forms:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "surveys": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "name": "Lost deal survey",
                        "live": true,
                        "template": "lost_deal",
                        "message": "Hi {first_name}, could you tell us what we could have done better? {survey_link}",
                        "subject": "A quick question from {business_name}",
                        "rules": [
                          {
                            "key": "lost",
                            "when": "lost",
                            "on": true,
                            "delay": {
                              "amount": 1,
                              "unit": "days"
                            },
                            "channel": "sms",
                            "sentence": "1 day after a deal is marked Lost, by text"
                          }
                        ],
                        "questions": [
                          {
                            "key": "lost_reason",
                            "question": "What was the main reason you didn't go with us?",
                            "type": "select",
                            "options": [
                              "Better pricing elsewhere",
                              "The timing wasn't right"
                            ],
                            "allow_other": true
                          }
                        ],
                        "public_url": "https://crm.example.com/f/lost-deal-survey-ab12",
                        "views": 80,
                        "answers": 31,
                        "page": "/clients/uuid/smart-forms/uuid",
                        "created_at": "2026-11-06T15:00:00Z",
                        "updated_at": "2026-11-07T15:00:00Z"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_survey",
        "tags": [
          "Smart forms"
        ],
        "summary": "Make a survey",
        "description": "A new survey from one of the app's five starts, with its questions, message and rule, as a draft: it sends nothing until it is live (`PATCH /v1/surveys/{form_id}/rules` with live: true). A sub-account keeps at most 100 Smart Forms.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "template": {
                    "type": "string",
                    "description": "Which start. Default blank.",
                    "enum": [
                      "lost_deal",
                      "won_deal",
                      "check_in",
                      "recommend",
                      "blank"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "description": "Up to 80 characters. Default the start's own."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "template": "lost_deal"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "survey": {
                      "id": "uuid",
                      "name": "Lost deal survey",
                      "live": false,
                      "template": "lost_deal",
                      "rules": [
                        {
                          "key": "lost",
                          "when": "lost",
                          "on": true,
                          "delay": {
                            "amount": 1,
                            "unit": "days"
                          },
                          "channel": "sms",
                          "sentence": "1 day after a deal is marked Lost, by text"
                        }
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/surveys/{form_id}/results": {
      "get": {
        "operationId": "get_survey_results",
        "tags": [
          "Smart forms"
        ],
        "summary": "A survey's answers",
        "description": "The Results tab as data. totals: answers, and of the links that went out how many were opened and answered.\n\nquestions:\n- per question, answers with counts and percents and `other_words` (what people typed under Other)\n- a rating's average, scores 1-10, `gave_9_or_10_pct` and `gave_6_or_less_pct`\n- a number's average\n- written answers (the first 50, `written_total` says how many)\n\n- responses: every answer, a page at a time.\n- Covers the newest 2,000 answers (capped says so).\n- Every member can read it.\n\nRequired scope: `smart_forms:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Survey id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Look back this many days, 1-3650. Default 90.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Responses per page, 1-100, default 25.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "survey": {
                      "id": "uuid",
                      "name": "Lost deal survey",
                      "live": true
                    },
                    "days": 90,
                    "totals": {
                      "answers": 31,
                      "sent": 120,
                      "opened": 74,
                      "opened_pct": 62,
                      "answered": 28,
                      "answered_pct": 23
                    },
                    "capped": false,
                    "questions": [
                      {
                        "key": "lost_reason",
                        "question": "What was the main reason you didn't go with us?",
                        "type": "select",
                        "answered": 31,
                        "answers": [
                          {
                            "answer": "Better pricing elsewhere",
                            "count": 14,
                            "pct": 45
                          },
                          {
                            "answer": "Other",
                            "count": 5,
                            "pct": 16
                          }
                        ],
                        "other_words": [
                          {
                            "text": "Went with my brother-in-law",
                            "lead_id": "uuid",
                            "name": "Jane Doe",
                            "at": "2026-11-07T15:00:00Z"
                          }
                        ]
                      }
                    ],
                    "responses": [
                      {
                        "id": "uuid",
                        "lead_id": "uuid",
                        "name": "Jane Doe",
                        "at": "2026-11-07T15:00:00Z",
                        "answers": [
                          {
                            "key": "lost_reason",
                            "question": "What was the main reason you didn't go with us?",
                            "answer": "Better pricing elsewhere"
                          }
                        ]
                      }
                    ],
                    "next_cursor": null
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/surveys/{form_id}/rules": {
      "patch": {
        "operationId": "update_survey_rules",
        "tags": [
          "Smart forms"
        ],
        "summary": "When a survey sends itself, its words, on or off",
        "description": "rules replaces the list (up to 4): when a deal is marked Won or Lost, the survey goes to that person after the wait, once per rule and person in 180 days, and not if the deal has moved on by then.\n\n- A rule on these messages real people automatically.\n- Send a rule's key to keep it; without one it takes over the old rule for the same event.\n- message and subject are what the personal link goes out in (`{first_name}`, `{business_name}`, `{survey_link}`).\n- live turns the survey on or off.\n- Send any of these; the rest stay.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Survey id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "rules": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 4 of { key, when: lost | won, delay: { amount, unit: hours | days | weeks | months }, channel: sms | email | both, on }."
                  },
                  "message": {
                    "type": "string",
                    "description": "Up to 600 characters."
                  },
                  "subject": {
                    "type": "string",
                    "description": "The email's subject, up to 150 characters."
                  },
                  "live": {
                    "type": "boolean",
                    "description": "On (links work and it can send) or off."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "rules": [
                  {
                    "when": "lost",
                    "delay": {
                      "amount": 2,
                      "unit": "days"
                    },
                    "channel": "sms"
                  }
                ],
                "live": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "survey": {
                      "id": "uuid",
                      "name": "Lost deal survey",
                      "live": true,
                      "rules": [
                        {
                          "key": "lost",
                          "when": "lost",
                          "on": true,
                          "delay": {
                            "amount": 2,
                            "unit": "days"
                          },
                          "channel": "sms",
                          "sentence": "2 days after a deal is marked Lost, by text"
                        }
                      ]
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/surveys/{form_id}/send": {
      "post": {
        "operationId": "send_survey",
        "tags": [
          "Smart forms"
        ],
        "summary": "Send a survey to people",
        "description": "Messages real people: each lead gets their own link, by text, email or both, through the queue (quiet hours, daily limits, STOP).\n\n- The first 25 go at once, the rest within minutes.\n- Up to 200 a send.\n- The survey must be live (400 otherwise).\n- Get lead ids from `GET /v1/leads`.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Survey id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lead_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "1-200 lead ids."
                  },
                  "channel": {
                    "type": "string",
                    "description": "Default sms (text; someone with only an email gets it by email).",
                    "enum": [
                      "sms",
                      "email",
                      "both"
                    ]
                  }
                },
                "required": [
                  "lead_ids"
                ],
                "additionalProperties": true
              },
              "example": {
                "lead_ids": [
                  "uuid"
                ],
                "channel": "sms"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "queued": 30,
                    "sent": 24,
                    "skipped": 1,
                    "failed": 0,
                    "retrying": 0,
                    "sending_soon": 5
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/surveys/{form_id}/links": {
      "post": {
        "operationId": "create_survey_link",
        "tags": [
          "Smart forms"
        ],
        "summary": "One lead's personal survey link",
        "description": "Their own link, to send however you like; nothing is sent. The same link comes back while it's unanswered (30 days). Answers land on this lead, with no name or phone asked. live says whether the survey is on, because a draft's links don't work yet.\n\nWho can call it: Owners and admins.\n\nRequired scope: `smart_forms:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "form_id",
            "in": "path",
            "required": true,
            "description": "Survey id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lead_id": {
                    "type": "string",
                    "description": "The lead."
                  }
                },
                "required": [
                  "lead_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "lead_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "link": "https://crm.example.com/f/lost-deal-survey-ab12?s=Ab12Cd34Ef56",
                    "lead_id": "uuid",
                    "live": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/reports/settings": {
      "get": {
        "operationId": "get_gbp_report_settings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google Reports settings",
        "description": "Tools > Google Reports: whether the weekly and monthly emails go, the day and hour (in the sub-account's time zone), who gets them, the check-ins, what the emails show and `next_note`, your note at the top of the next one. saved is false until someone saves them, and the settings are then the defaults.\n\nWho can call it: Owners and admins, with the Google tools add-on (403 `addon_locked` without it).\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "settings": {
                      "enabled": true,
                      "weekly": true,
                      "monthly": true,
                      "send_day": 1,
                      "send_hour": 8,
                      "recipients": [
                        "owner@acmeroofing.com"
                      ],
                      "nudge_reviews_days": 14,
                      "nudge_photos": true,
                      "nudge_wins": true,
                      "show_drops": false,
                      "compare": true,
                      "rank_maps": true,
                      "next_note": "This month we added your new services and set your holiday hours.",
                      "last_weekly_at": "2026-11-02T13:00:00Z",
                      "last_monthly_at": "2026-11-04T13:00:00Z",
                      "updated_at": "2026-11-01T15:00:00Z"
                    },
                    "saved": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "put": {
        "operationId": "set_gbp_report_settings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change the Google Reports settings",
        "description": "The app's Save. Send only what changes. Turning reports on needs someone to send them to (400 otherwise). enabled: true means real emails go to recipients, in the agency's brand, on their schedule.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Reports on or off."
                  },
                  "weekly": {
                    "type": "boolean",
                    "description": "The weekly summary."
                  },
                  "monthly": {
                    "type": "boolean",
                    "description": "The monthly report (first weekday from the 4th)."
                  },
                  "send_day": {
                    "type": "number",
                    "description": "The weekly's day: 0 = Sunday ... 6 = Saturday."
                  },
                  "send_hour": {
                    "type": "number",
                    "description": "The hour, 5 to 20, in the sub-account's time zone."
                  },
                  "recipients": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 10 email addresses."
                  },
                  "nudge_reviews_days": {
                    "type": "number",
                    "description": "Check-in after this many days without a new Google review: 7, 10, 14, 21 or 30; null for off."
                  },
                  "nudge_photos": {
                    "type": "boolean",
                    "description": "Check-in when automatic photo uploads have under a week left."
                  },
                  "nudge_wins": {
                    "type": "boolean",
                    "description": "Check-in after a great week of reviews."
                  },
                  "show_drops": {
                    "type": "boolean",
                    "description": "Show numbers that went down too (off: only gains get a %)."
                  },
                  "compare": {
                    "type": "boolean",
                    "description": "This period next to the one before."
                  },
                  "rank_maps": {
                    "type": "boolean",
                    "description": "The Map Rankings heat maps."
                  },
                  "next_note": {
                    "type": "string",
                    "description": "Your words at the top of the next weekly or monthly report, in your name, up to 1,200 characters; cleared once that one goes out. null clears it now."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "enabled": true,
                "recipients": [
                  "owner@acmeroofing.com"
                ],
                "send_day": 1,
                "send_hour": 8
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "settings": {
                      "enabled": true,
                      "weekly": true,
                      "monthly": true,
                      "send_day": 1,
                      "send_hour": 8,
                      "recipients": [
                        "owner@acmeroofing.com"
                      ],
                      "nudge_reviews_days": 14,
                      "nudge_photos": true,
                      "nudge_wins": true,
                      "show_drops": false,
                      "compare": true,
                      "rank_maps": true,
                      "next_note": null,
                      "last_weekly_at": null,
                      "last_monthly_at": null,
                      "updated_at": "2026-11-08T15:00:00Z"
                    },
                    "saved": true
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/reports": {
      "get": {
        "operationId": "list_gbp_reports",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Google report emails sent",
        "description": "Newest first: each email's kind, status (sent, failed, sending), who got it, the numbers it showed for each business (reviews, posts, photos, Google's own numbers, Map Rankings) and link, the public web version anyone with the link can open.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only this kind.",
            "schema": {
              "type": "string",
              "enum": [
                "weekly",
                "monthly",
                "reviews_quiet",
                "photos_low",
                "wins"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-30, default 10.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "reports": [
                      {
                        "id": "uuid",
                        "kind": "weekly",
                        "subject": "Your week on Google",
                        "test": false,
                        "status": "sent",
                        "recipients": [
                          "owner@acmeroofing.com"
                        ],
                        "sent_at": "2026-11-02T13:00:00Z",
                        "opened_at": null,
                        "created_at": "2026-11-02T13:00:00Z",
                        "period": {
                          "start": "2026-10-26T04:00:00Z",
                          "end": "2026-11-02T05:00:00Z",
                          "label": "Oct 26 - Nov 1"
                        },
                        "link": "https://crm.example.com/google-report/9f1c2a",
                        "headline": "A strong week on Google",
                        "highlights": [
                          "New reviews averaged 4.8 stars"
                        ],
                        "work": [
                          {
                            "label": "Reviews answered",
                            "n": 3
                          }
                        ],
                        "review_page": {
                          "sent": 4,
                          "rated": 3,
                          "to_google": 2,
                          "written": 1
                        },
                        "businesses": [
                          {
                            "profile_id": "uuid",
                            "name": "Acme Roofing",
                            "rating": 4.9,
                            "review_count": 120,
                            "reviews": {
                              "new": 3,
                              "average": 4.8,
                              "replied": 3,
                              "waiting": 0
                            },
                            "posts": {
                              "published": 1,
                              "upcoming": 2
                            },
                            "photos": {
                              "added": 2,
                              "queued": 5,
                              "days_left": 12
                            },
                            "google": {
                              "days": 7,
                              "until": "2026-10-30",
                              "current": {
                                "searches": 410,
                                "maps": 220,
                                "calls": 9,
                                "directions": 4,
                                "website": 31,
                                "bookings": 0
                              },
                              "previous": {
                                "searches": 380,
                                "maps": 200,
                                "calls": 7,
                                "directions": 6,
                                "website": 28,
                                "bookings": 0
                              }
                            },
                            "previous": null,
                            "rankings": [
                              {
                                "keyword": "roofer",
                                "average": 2.4,
                                "previous_average": 3,
                                "first_average": 8.1,
                                "top_3_percent": 72,
                                "points": 49,
                                "leader": {
                                  "name": "Another Roofer",
                                  "rating": 4.7,
                                  "reviews": 80
                                },
                                "scanned_at": "2026-11-01T12:00:00Z"
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/reports/test": {
      "post": {
        "operationId": "send_gbp_report_test",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Send a test Google report to yourself",
        "description": "The app's Send me a test: the report as it would go now, marked [Test], to the email of the person this key belongs to and nobody else. It takes no address. 400 until the business is found on Google.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "kind": {
                    "type": "string",
                    "description": "Default weekly.",
                    "enum": [
                      "weekly",
                      "monthly",
                      "reviews_quiet",
                      "photos_low",
                      "wins"
                    ]
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "kind": "monthly"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "sent": true,
                    "kind": "monthly",
                    "to": "you@agency.com",
                    "link": "https://crm.example.com/google-report/9f1c2a"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/holiday-hours": {
      "get": {
        "operationId": "get_gbp_holiday_hours",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Holiday hours on Google",
        "description": "What a Google profile shows now on the coming US holidays (75 days) and on its other special days ahead: hours is closed, the hours that day (\"09:00-14:00\") or null with set false (nothing set: Google shows the usual hours).\n\n- `has_regular_hours` false means Google needs regular hours before holiday hours.\n- Read live from Google.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One of its Google profiles (default its first).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile_id": "uuid",
                    "title": "Acme Roofing",
                    "region": "US",
                    "has_regular_hours": true,
                    "holidays": [
                      {
                        "date": "2026-11-26",
                        "key": "thanksgiving",
                        "name": "Thanksgiving",
                        "set": true,
                        "hours": "closed"
                      },
                      {
                        "date": "2026-12-24",
                        "key": "christmas_eve",
                        "name": "Christmas Eve",
                        "set": false,
                        "hours": null
                      }
                    ],
                    "other_days": [
                      {
                        "date": "2027-01-15",
                        "set": true,
                        "hours": "10:00-14:00"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "set_gbp_holiday_hours",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Set holiday hours on Google",
        "description": "Sets the days sent on the Google profile, live: closed, usual or its own hours.\n\n- Every other special day stays as it is.\n- Recorded like a Profile Optimizer change (undo it with `POST /v1/google-business/optimizer/changes/{change_id}/undo`) and listed in the client's next report.\n- 400 with Google's reason when it refuses.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its Google profiles (default its first)."
                  },
                  "days": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 12 days: { date: \"2026-11-26\", hours: \"closed\" | \"usual\" | \"09:00-14:00\", name?: \"Thanksgiving\" }. usual is that weekday's regular hours. From today (the business's time zone) to a year out."
                  }
                },
                "required": [
                  "workspace_id",
                  "days"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "days": [
                  {
                    "date": "2026-11-26",
                    "hours": "closed",
                    "name": "Thanksgiving"
                  },
                  {
                    "date": "2026-12-24",
                    "hours": "09:00-14:00",
                    "name": "Christmas Eve"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile_id": "uuid",
                    "days": [
                      {
                        "date": "2026-11-26",
                        "name": "Thanksgiving",
                        "set": true,
                        "hours": "closed"
                      },
                      {
                        "date": "2026-12-24",
                        "name": "Christmas Eve",
                        "set": true,
                        "hours": "09:00-14:00"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/profile": {
      "get": {
        "operationId": "get_gbp_profile_details",
        "tags": [
          "Ads & Google"
        ],
        "summary": "A Google profile, as Google has it now",
        "description": "Everything that can be edited by hand on a Google Business Profile, read live from Google: the website link, phone, description, hours (each day's open stretches; an empty day is closed, 00:00 to 24:00 is open all day), opening date, main and extra categories, services (id, kind google or custom, name, description, the category it sits under), `service_catalog` (Google's own services for each of its categories, `on_profile` true for the ones already there), the Book button's link, its booking calendars, and the social links Google offers this business. `pending_review` true means Google is still reviewing an earlier edit.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One of its Google profiles (default its first).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile_id": "uuid",
                    "title": "Acme Roofing",
                    "address": "12 Main St, Jacksonville, FL, 32202",
                    "maps_url": "https://maps.google.com/?cid=123",
                    "pending_review": false,
                    "website": "https://acmeroofing.com/",
                    "phone": "(904) 555-0142",
                    "description": "Family roofers since 1998.",
                    "hours": {
                      "MONDAY": [
                        {
                          "open": "08:00",
                          "close": "17:00"
                        }
                      ],
                      "TUESDAY": [
                        {
                          "open": "08:00",
                          "close": "17:00"
                        }
                      ],
                      "WEDNESDAY": [
                        {
                          "open": "08:00",
                          "close": "17:00"
                        }
                      ],
                      "THURSDAY": [
                        {
                          "open": "08:00",
                          "close": "17:00"
                        }
                      ],
                      "FRIDAY": [
                        {
                          "open": "08:00",
                          "close": "17:00"
                        }
                      ],
                      "SATURDAY": [],
                      "SUNDAY": []
                    },
                    "opening_date": {
                      "year": 1998,
                      "month": 4
                    },
                    "categories": {
                      "primary": {
                        "id": "categories/gcid:roofing_contractor",
                        "name": "Roofing contractor"
                      },
                      "additional": [
                        {
                          "id": "categories/gcid:gutter_service",
                          "name": "Gutter service"
                        }
                      ]
                    },
                    "services": [
                      {
                        "id": "st:job_type_id:roof_repair",
                        "kind": "google",
                        "name": "Roof repair",
                        "description": "Leaks and missing shingles fixed the same week.",
                        "category": "categories/gcid:roofing_contractor"
                      },
                      {
                        "id": "ff:storm damage tarping",
                        "kind": "custom",
                        "name": "Storm damage tarping",
                        "description": "",
                        "category": "categories/gcid:roofing_contractor"
                      }
                    ],
                    "can_edit_services": true,
                    "service_catalog": [
                      {
                        "id": "categories/gcid:roofing_contractor",
                        "name": "Roofing contractor",
                        "services": [
                          {
                            "service_type_id": "job_type_id:roof_repair",
                            "name": "Roof repair",
                            "on_profile": true
                          },
                          {
                            "service_type_id": "job_type_id:roof_inspection",
                            "name": "Roof inspection",
                            "on_profile": false
                          }
                        ]
                      }
                    ],
                    "booking_link": {
                      "url": "",
                      "editable": true
                    },
                    "calendars": [
                      {
                        "id": "uuid",
                        "name": "Estimates",
                        "url": "https://crm.acme.com/c/estimates"
                      }
                    ],
                    "links": [
                      {
                        "id": "url_facebook",
                        "name": "Facebook",
                        "url": "https://facebook.com/acmeroofing"
                      },
                      {
                        "id": "url_instagram",
                        "name": "Instagram",
                        "url": ""
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "edit_gbp_profile_details",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Edit a Google profile by hand",
        "description": "Changes the fields sent on the business's live Google profile, which everyone sees.\n\n- Each field goes to Google on its own, against the profile as it is at that moment, and answers its own result (ok with what changed, or Google's reason), so one refused field doesn't stop the rest; a field already like that on Google answers ok with a message and changes nothing.\n- Services and categories are steps (add, update, remove), never a whole list, so an edit made on Google meanwhile is kept.\n- Every change is recorded like a Profile Optimizer change: undo it with `POST /v1/google-business/optimizer/changes/{change_id}/undo`, and the client's next report lists it.\n- `dry_run`: true has Google validate without saving (the Book link and social links have no such check and are skipped).\n- Never changed here: the business name, the address and the main category.\n- A new phone number can make Google ask to verify the business again.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its Google profiles (default its first)."
                  },
                  "website": {
                    "type": "string",
                    "description": "The website link; \"\" takes it off."
                  },
                  "phone": {
                    "type": "string",
                    "description": "The main phone number, 7 to 15 digits."
                  },
                  "hours": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "The whole week: { MONDAY: [{ open: \"08:00\", close: \"17:00\" }], ... }. A day left out or with an empty list is closed, up to 3 stretches a day, 00:00 to 24:00 is open all day, a close before the open runs past midnight."
                  },
                  "description": {
                    "type": "string",
                    "description": "Up to 750 characters, no links; \"\" clears it."
                  },
                  "services": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ add: [{ kind: \"google\", service_type_id, description? } | { kind: \"custom\", name, category, description? }], update: [{ id, description?, name? }], remove: [id] }. Ids and service_type_ids come from GET /v1/google-business/profile; a custom name can only be changed on a custom service; descriptions up to 300 characters."
                  },
                  "categories": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ add: [category id], remove: [category id] } for the extra categories (up to 9). Ids like categories/gcid:gutter_service."
                  },
                  "booking_link": {
                    "type": "string",
                    "description": "The Book button's link, \"\" to take it off, or { calendar_id } for one of its booking calendars."
                  },
                  "links": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Social links by id from GET /v1/google-business/profile: { url_facebook: \"https://facebook.com/acme\", url_instagram: \"\" } (\"\" takes one off)."
                  },
                  "opening_date": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "{ year, month } the business opened."
                  },
                  "dry_run": {
                    "type": "boolean",
                    "description": "true: Google validates, nothing changes."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "website": "https://acmeroofing.com/jacksonville",
                "services": {
                  "add": [
                    {
                      "kind": "custom",
                      "name": "Skylight installation",
                      "category": "categories/gcid:roofing_contractor",
                      "description": "New skylights, flashed and sealed."
                    }
                  ],
                  "remove": [
                    "ff:storm damage tarping"
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile_id": "uuid",
                    "dry_run": false,
                    "results": [
                      {
                        "field": "website",
                        "ok": true,
                        "changed": "Changed the website link to acmeroofing.com/jacksonville"
                      },
                      {
                        "field": "services",
                        "ok": true,
                        "changed": "Added 1 service, Removed 1 service"
                      }
                    ],
                    "profile": {
                      "profile_id": "uuid",
                      "title": "Acme Roofing",
                      "website": "https://acmeroofing.com/jacksonville"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/embeds": {
      "get": {
        "operationId": "list_gbp_embeds",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Website embeds",
        "description": "Tools > Website embeds: review widgets, photo galleries, Latest updates, FAQs and schema markup, each with snippet, the one line to paste on the business's website. Each is drawn from the live Google data.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One Google business (default all).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "embeds": [
                      {
                        "id": "uuid",
                        "workspace_id": "uuid",
                        "profile_id": "uuid",
                        "kind": "reviews",
                        "name": "Reviews",
                        "settings": {
                          "theme": "light",
                          "accent": "#1a73e8",
                          "radius": 14,
                          "font": "site",
                          "heading": "What our customers say",
                          "layout": "carousel",
                          "minStars": 4,
                          "max": 12,
                          "showReply": false,
                          "reviewButton": true,
                          "buttonText": "Leave a review",
                          "summary": true,
                          "hidden": []
                        },
                        "faq": [],
                        "facts": null,
                        "facts_at": null,
                        "created_at": "2026-11-05T15:00:00Z",
                        "updated_at": "2026-11-05T15:00:00Z",
                        "snippet": "<div data-gbp-embed=\"3f1a...\"></div><script src=\"https://crm.example.com/api/public/gbp-embed/3f1a....js\" async></script>"
                      }
                    ]
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "create_gbp_embed",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Make a website embed",
        "description": "One widget for the business's website, on its Google business (`profile_id`, default its first).\n\n- Nothing shows anywhere until its snippet is pasted on a site.\n- Settings a kind doesn't have, or a value it wouldn't keep, are refused (400).\n- At most 100 per sub-account.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its Google businesses (default its first)."
                  },
                  "kind": {
                    "type": "string",
                    "description": "What it shows.",
                    "enum": [
                      "reviews",
                      "photos",
                      "posts",
                      "faq",
                      "schema"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "description": "For the team, up to 80 characters (default the kind's name)."
                  },
                  "settings": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Every kind but schema: theme (light, dark, auto), accent (#rrggbb), radius (0-28), font (site, system), heading. reviews: layout (carousel, grid, list, badge), minStars (4, 5), max (1-30), showReply, reviewButton, buttonText, summary, hidden (review ids not to show). photos: layout (grid, masonry, mosaic, carousel, slideshow), max (1-96), columns (2-6), phoneColumns (1-3), ratio (square, landscape, wide, portrait), fit (cover, contain), gap (none, s, m, l), paging (all, more, pages; grid, masonry and mosaic) with rows (1-8) and buttonText / buttonStyle for the Show more button, arrows (top, sides, none), dots, autoplay (0, 4, 6, 8) and thumbs for the carousel and slideshow, captions (none, hover, always), hover (zoom, dim, none), lightbox, order (newest, oldest, shuffle), hidden (photo ids not to show, as in the embed JSON; the gallery shows the photos already on the Google profile and the ones sent through the tools). posts: layout (cards, list), max (1-12), open (modal, google). faq: openFirst, schema. schema: type (a schema.org type or auto), url."
                  },
                  "faq": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "FAQ only: up to 20 { q, a } (a question up to 200 characters, an answer up to 1,200)."
                  }
                },
                "required": [
                  "workspace_id",
                  "kind"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid",
                "kind": "reviews",
                "name": "Homepage reviews",
                "settings": {
                  "layout": "grid",
                  "max": 6
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "embed": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "kind": "reviews",
                      "name": "Homepage reviews",
                      "settings": {
                        "layout": "grid",
                        "max": 6
                      },
                      "faq": [],
                      "facts": null,
                      "facts_at": null,
                      "created_at": "2026-11-08T15:00:00Z",
                      "updated_at": "2026-11-08T15:00:00Z",
                      "snippet": "<div data-gbp-embed=\"3f1a...\"></div><script src=\"https://crm.example.com/api/public/gbp-embed/3f1a....js\" async></script>"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/embeds/{embed_id}": {
      "patch": {
        "operationId": "update_gbp_embed",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change a website embed",
        "description": "Changes what visitors see on any site it's pasted on, at once. Send only what changes: settings merge onto the saved ones (hide a review by putting its id in `settings.hidden`), faq replaces the whole list. Its kind and the line to paste never change.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "embed_id",
            "in": "path",
            "required": true,
            "description": "Embed id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Up to 80 characters."
                  },
                  "settings": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "As POST /v1/google-business/embeds."
                  },
                  "faq": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "FAQ only: the whole list of { q, a }."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "settings": {
                  "hidden": [
                    "review-uuid"
                  ],
                  "minStars": 5
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "embed": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "kind": "reviews",
                      "name": "Homepage reviews",
                      "settings": {
                        "minStars": 5,
                        "hidden": [
                          "review-uuid"
                        ]
                      },
                      "faq": [],
                      "facts": null,
                      "facts_at": null,
                      "created_at": "2026-11-08T15:00:00Z",
                      "updated_at": "2026-11-08T16:00:00Z",
                      "snippet": "<div data-gbp-embed=\"3f1a...\"></div><script src=\"https://crm.example.com/api/public/gbp-embed/3f1a....js\" async></script>"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "delete_gbp_embed",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Delete a website embed",
        "description": "It stops showing on any site it's pasted on.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "embed_id",
            "in": "path",
            "required": true,
            "description": "Embed id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "deleted": true,
                    "id": "uuid"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/embeds/{embed_id}/faq": {
      "post": {
        "operationId": "write_gbp_embed_faq",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Have the AI write an FAQ",
        "description": "Free. Writes new questions from the business's own facts (its Google profile, the AI Brain, its hours) and what its reviews keep mentioning, and drops any answer claiming what those facts don't say (dropped counts them).\n\n- Nothing is saved: written is what's new, faq the list with them added; check it and send it with `PATCH /v1/google-business/embeds/{embed_id}`.\n- FAQ embeds only.\n- 409 `not_enough_facts` until the Optimizer has run or the AI Brain has facts; 409 `faq_full` at 20 questions.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "embed_id",
            "in": "path",
            "required": true,
            "description": "An FAQ embed's id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "written": [
                      {
                        "q": "Are you insured?",
                        "a": "Yes, we're licensed and insured."
                      }
                    ],
                    "faq": [
                      {
                        "q": "Are you insured?",
                        "a": "Yes, we're licensed and insured."
                      }
                    ],
                    "dropped": 0,
                    "saved": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/embeds/{embed_id}/facts": {
      "post": {
        "operationId": "refresh_gbp_embed_facts",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Read the business from Google Maps",
        "description": "Reads the pin, opening hours, type, phone, website and address from Google Maps onto every embed of that business, for its schema markup and FAQ.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "embed_id",
            "in": "path",
            "required": true,
            "description": "Embed id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "embed": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "profile_id": "uuid",
                      "kind": "schema",
                      "name": "Business schema",
                      "settings": {
                        "type": "auto",
                        "url": ""
                      },
                      "faq": [],
                      "facts": {
                        "name": "Acme Roofing",
                        "phone": "+1 904-555-0123"
                      },
                      "facts_at": "2026-11-08T15:00:00Z",
                      "created_at": "2026-11-05T15:00:00Z",
                      "updated_at": "2026-11-08T15:00:00Z",
                      "snippet": "<script src=\"https://crm.example.com/api/public/gbp-embed/3f1a....js\" async></script>"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/connect-link": {
      "post": {
        "operationId": "make_gbp_connect_link",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Make or get the owner's Google connect link",
        "description": "For a business whose owner should connect Google without the CRM: a page on the CRM's own domain, in the agency's brand, with no sign-in.\n\n- It answers with the working link, or makes one when there's none, it expired (14 days) or it was used; reset: true replaces it.\n- Only a Google account that manages this business can save a connection through it.\n- state is ready, expired, connected or off.\n- Anyone holding the link can open the page, so send it only to the owner.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string",
                    "description": "Sub-account id (omit on keys restricted to one sub-account)."
                  },
                  "profile_id": {
                    "type": "string",
                    "description": "One of its Google businesses (default its first)."
                  },
                  "reset": {
                    "type": "boolean",
                    "description": "true: the old link stops working and a new one is made."
                  }
                },
                "required": [
                  "workspace_id"
                ],
                "additionalProperties": true
              },
              "example": {
                "workspace_id": "uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile_id": "uuid",
                    "connect_link": {
                      "state": "ready",
                      "url": "https://crm.example.com/google-connect/AbCd1234",
                      "expires_at": "2026-11-22T15:00:00Z",
                      "opened_at": null,
                      "connected_at": null,
                      "connected_email": null,
                      "business": "Acme Roofing",
                      "business_matched": false
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "turn_off_gbp_connect_link",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Turn off the owner's Google connect link",
        "description": "The link stops working. A connection already made through it stays.\n\nWho can call it: Owners and admins.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One of its Google businesses (default its first).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile_id": "uuid",
                    "connect_link": {
                      "state": "off",
                      "url": null
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/photo-link": {
      "get": {
        "operationId": "get_gbp_photo_link",
        "tags": [
          "Ads & Google"
        ],
        "summary": "The crew's photo link and PIN",
        "description": "The link and 4-digit PIN crews use to add job photos to the Google profile with no sign-in (made the first time, as in the app). Give them only to the crew: both together can add photos to the line.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "query",
            "required": false,
            "description": "One of its Google businesses (default its first).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile_id": "uuid",
                    "photo_link": {
                      "url": "https://crm.example.com/photos/AbCd1234",
                      "pin": "4821"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/google-business/profiles/{profile_id}": {
      "patch": {
        "operationId": "update_gbp_profile_settings",
        "tags": [
          "Ads & Google"
        ],
        "summary": "Change a Google profile's own settings",
        "description": "Local knowledge (the Optimizer may name places from it), the words review replies work in now and then, and whether photos going to Google carry a location (a job's own GPS first, then this spot, then the business's pin).\n\n- Send only what changes; `geotag_lat` and `geotag_lng` go together and null clears the spot.\n- Auto-replies and auto-posting stay in the app.\n\nWho can call it: Owners and admins, with the Google tools add-on.\n\nRequired scope: `workspaces:write`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique string per logical operation. Replays within 24h return the original response instead of creating a duplicate or double-charging.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "profile_id",
            "in": "path",
            "required": true,
            "description": "Profile id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "local_notes": {
                    "type": "string",
                    "description": "Streets, neighborhoods, landmarks and weather its customers know, up to 1,500 characters; null clears it."
                  },
                  "replies_keywords": {
                    "type": "string",
                    "description": "Services and towns, comma separated, up to 400 characters; null clears it."
                  },
                  "photos_geotag": {
                    "type": "boolean",
                    "description": "Photos going to Google carry a location."
                  },
                  "geotag_lat": {
                    "type": "number",
                    "description": "With geotag_lng; null clears the spot."
                  },
                  "geotag_lng": {
                    "type": "number",
                    "description": "With geotag_lat."
                  },
                  "geotag_place": {
                    "type": "string",
                    "description": "The spot's name, up to 200 characters (goes with geotag_lat and geotag_lng)."
                  }
                },
                "additionalProperties": true
              },
              "example": {
                "local_notes": "Most jobs are in Riverside and San Marco; salt air is hard on metal roofs.",
                "photos_geotag": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "profile": {
                      "id": "uuid",
                      "workspace_id": "uuid",
                      "local_notes": "Most jobs are in Riverside and San Marco; salt air is hard on metal roofs.",
                      "replies_keywords": null,
                      "photos_geotag": true,
                      "geotag_lat": null,
                      "geotag_lng": null,
                      "geotag_place": null,
                      "updated_at": "2026-11-08T15:00:00Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/texting-registration": {
      "get": {
        "operationId": "get_texting_registration",
        "tags": [
          "Setup"
        ],
        "summary": "Where the texting registration stands",
        "description": "Read only.\n\n- The business's A2P registration with the phone carriers, as the business sees it in Settings > Phone: kind (business or `sole_proprietor`), status (draft, `brand_pending`, `needs_code`, `campaign_pending`, approved, `needs_fix`, `on_hold` or closed), `whose_move` (you, us, carriers or nobody), message and needed in plain words, reasons when it was turned down (each with what to fix), and whether the business's numbers are on its own registration yet.\n- registration is null when none was started.\n- `texting_live`, numbers and `numbers_ready` say whether a number can text now, the same reading as `texting_ready` on `GET /v1/phone-numbers`; a status can be up to about 10 minutes old.\n- Filing or fixing a registration and buying a number stay in the app on purpose: they take the business's legal details and a fee that isn't refunded.\n- A tax ID or personal cell number is never returned.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `phone_numbers:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "registration": {
                      "kind": "business",
                      "status": "needs_fix",
                      "since": "2026-11-02T00:00:00Z",
                      "display_name": "Acme",
                      "legal_name": "Acme LLC",
                      "test_registration": false,
                      "whose_move": "you",
                      "message": "The carriers turned down the details.",
                      "needed": "Use your exact legal name. Then send it again in Settings > Phone in the app.",
                      "problem": "The legal name doesn't match",
                      "reasons": [
                        {
                          "title": "The name doesn't match",
                          "fix": "Use your exact legal name.",
                          "carrier_said": "TAX_ID mismatch"
                        }
                      ],
                      "numbers_on_own_registration": false,
                      "submitted_at": "2026-11-01T00:00:00Z",
                      "approved_at": null,
                      "closed_at": null
                    },
                    "texting_live": true,
                    "numbers": 1,
                    "numbers_ready": 1,
                    "page": "/clients/uuid/settings?tab=twilio"
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/number-orders": {
      "get": {
        "operationId": "list_number_orders",
        "tags": [
          "Setup"
        ],
        "summary": "Numbers on order outside the US",
        "description": "Read only. A number in a country whose regulator wants paperwork is an order the carrier reviews before it exists.\n\n- Newest first: country, number, status (review, `needs_fix`, active or cancelled), `whose_move` (you, us, carriers or nobody), message and needed in plain words, and each requirement's name, type and status (approved, `turned_down` or waiting).\n- Buying a number and sending or fixing its paperwork stay in the app on purpose.\n- Countries with no paperwork have no order.\n\nWho can call it: Owners and admins only.\n\nRequired scope: `phone_numbers:read`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "description": "Sub-account id (omit on keys restricted to one sub-account).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "review, needs_fix, active or cancelled.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-100, default 25.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per window for this key."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests left in the current window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix seconds when the window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                "example": {
                  "success": true,
                  "data": {
                    "orders": [
                      {
                        "id": "uuid",
                        "country": "GB",
                        "country_name": "United Kingdom",
                        "number_type": "mobile",
                        "phone_number": "+447911123456",
                        "status": "needs_fix",
                        "whose_move": "you",
                        "message": "The carrier needs a change.",
                        "needed": "Upload a newer proof of address. Then send them again in the app.",
                        "requirements": [
                          {
                            "name": "Proof of address",
                            "type": "document",
                            "status": "turned_down"
                          }
                        ],
                        "created_at": "2026-11-05T00:00:00Z",
                        "activated_at": null,
                        "cancelled_at": null
                      }
                    ],
                    "has_more": false
                  },
                  "error": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key, e.g. `zu-...`. An admin creates one in Settings → API."
      }
    },
    "schemas": {
      "SuccessEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "success"
        ]
      },
      "ConfirmationRequired": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          },
          "confirmation_required": {
            "type": "boolean",
            "const": true
          },
          "confirmation_token": {
            "type": "string",
            "description": "Single-use, expires after 10 minutes."
          },
          "estimated_credits": {
            "type": "number"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "data": {
            "type": "null"
          },
          "error": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Requests allowed per window for this key."
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Requests left in the current window."
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            },
            "description": "Unix seconds when the window resets."
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait before retrying."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ConfirmationRequired": {
        "description": "Confirmation required, or not enough credits. Re-send the identical request with the returned confirmation_token to proceed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ConfirmationRequired"
            }
          }
        }
      },
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    }
  }
}